前言 本文记录了使用 Hugo 静态站点生成器搭配 PaperMod 主题，在云服务器上搭建一个技术博客的全过程。包括：环境配置、部署上线、后台管理、美化、搜索、评论等功能，并附上所有踩过的坑和解决方案。
适用人群：有一台云服务器（本文以 Ubuntu/Debian 为例）、一个公网 IP 或域名，想快速搭建可在线编辑的技术博客。
最终效果：一个基于 IP 即可访问的静态博客，可通过浏览器后台在线编辑文章，刷新页面即可生效。
一、服务器基础环境
更新系统并安装必要软件
udo apt update && sudo apt upgrade -y
sudo apt install git nginx certbot python3-certbot-nginx -y
安装 Hugo（推荐 snap）
sudo snap install hugo
若不用 snap，可去 GitHub Release 下载最新 deb 包安装。但请确保版本 ≥ 0.146.0，否则 PaperMod 最新版会报错。
检查版本： hugo version
二、创建 Hugo 站点
创建工作目录 sudo mkdir -p /var/www/techblog
sudo chown -R
USER:USER /var/www/techblog
cd /var/www/techblog
初始化 Hugo 站点 hugo new site . –force 此时会生成 hugo.toml 及标准目录结构。
安装 PaperMod 主题 git init
git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
cd themes/PaperMod
git checkout v8.0 # 使用与 Hugo 0.146.0 兼容的稳定版本
cd ../..
三、配置文件 hugo.toml 将以下内容写入 hugo.toml（注意替换占位符）：
baseURL = “http://你的公网IP/”
languageCode = “zh-cn”
defaultContentLanguage = “zh-cn”
title = “你的博客标题”
enableEmoji = true
theme = “PaperMod”
[pagination]
pagerSize = 10
[markup]
[markup.highlight]
style = “monokai”
lineNos = true
anchorLineNos = false
codeFences = true
guessSyntax = true
tabWidth = 4
[markup.goldmark]
[markup.goldmark.renderer]
unsafe = true
[markup.goldmark.extensions]
strikethrough = true
taskList = true
[[menu.main]]
name = “文章”
url = “/posts/”
weight = 1
[[menu.main]]
name = “标签”
url = “/tags/”
weight = 2
[[menu.main]]
name = “分类”
url = “/categories/”
weight = 3
[[menu.main]]
name = “关于”
url = “/about/”
weight = 4
[outputs]
home = [“HTML”, “RSS”, “JSON”]
[params]
description = “我的技术思考与记录”
author = “你的名字”
dateFormat = “2006-01-02”
readingTime = true
ShowSearch = true
ShowCodeCopyButtons = true
ShowBreadCrumbs = true
env = “production”
首页个人介绍（如果不想要头像模式，可以注释掉 profileMode 三行）
profileMode = true
avatar = “images/avatar.jpg”
bio = “全栈开发 / 技术博客作者”
评论（Utterances）
[params.utterances]
repo = “你的GitHub用户名/评论仓库名”
issueTerm = “pathname”
theme = “github-light”
label = “评论”
社交链接
[[params.social]]
name = “GitHub”
url = “https://github.com/你的用户名”
icon = “github”
[[params.social]]
name = “邮箱”
url = “mailto:you@example.com”
icon = “email”
数学公式
[params.math]
enable = true
engine = “katex”
关键注意点：
所有数值、字符串都要使用英文半角引号 “"。
[outputs] 必须独立成块，且包含 JSON。
[params.math] 要用单括号，不能用双括号。
切勿在 [params] 外再写 author = …，TOML 不允许重复键。
四、创建第一篇文章并生成静态页面
创建文章目录
mkdir -p content/posts
新建文章
hugo new posts/hello-world.md 编辑 content/posts/hello-world.md，将 draft: true 改为 false，并写入一些内容。
生成静态网站
hugo
生成的网站文件在 public/ 目录。
五、配置 Nginx
创建站点配置文件
sudo nano /etc/nginx/sites-available/techblog 内容：
server {
listen 80;
server_name _;
root /var/www/techblog/public;
index index.html index.htm;
location / {
try_files
uriuri/ =404;
}
access_log /var/log/nginx/techblog_access.log;
error_log /var/log/nginx/techblog_error.log;
}
启用站点
sudo rm /etc/nginx/sites-enabled/default # 删除默认欢迎页
sudo ln -s /etc/nginx/sites-available/techblog /etc/nginx/sites-enabled/techblog
sudo nginx -t
sudo systemctl reload nginx
云服务器防火墙放行 80 端口 登录云控制台，在安全组中添加入方向规则：允许 TCP 80 端口，授权对象 0.0.0.0/0。
如果使用 ufw：
sudo ufw allow 80/tcp
访问 http://你的公网IP 即可看到博客首页。
六、搭建浏览器管理后台（FileBrowser）
安装 FileBrowser
curl -fsSL https://raw.githubusercontent.com/filebrowser/get/master/get.sh | bash
初始化数据库并创建管理员
sudo mkdir -p /etc/filebrowser
filebrowser -d /etc/filebrowser/filebrowser.db config init
filebrowser -d /etc/filebrowser/filebrowser.db users add 用户名 密码 –perm.admin
启动服务（监听所有 IP）
filebrowser -a 0.0.0.0 -p 8080 -r /var/www/techblog/content -d /etc/filebrowser/filebrowser.db
放行 8080 端口
sudo ufw allow 8080/tcp 云控制台同样需添加 8080 入方向规则。
设为系统服务（防重启丢失）
创建 /etc/systemd/system/filebrowser.service：
[Unit]
Description=File Browser
After=network.target
[Service]
ExecStart=/usr/local/bin/filebrowser -a 0.0.0.0 -p 8080 -r /var/www/techblog/content -d /etc/filebrowser/filebrowser.db
Restart=on-failure
[Install]
WantedBy=multi-user.target
然后执行：
sudo systemctl daemon-reload
sudo systemctl enable filebrowser
sudo systemctl start filebrowser
访问 http://你的IP:8080 即可进入文件管理器，可以直接编辑 Markdown 文件。
自动构建（每次改完文章后执行 hugo） 在服务器上，改完文章后需手动生成：
cd /var/www/techblog && hugo
你也可以将 FileBrowser 的根目录设为整个站点，编辑后执行脚本，或使用 Git 钩子实现自动化。
七、美化与自定义
修改配色和字体 创建自定义 CSS 文件：
mkdir -p /var/www/techblog/assets/css/extended
nano /var/www/techblog/assets/css/extended/custom.css
示例内容（覆盖 PaperMod 默认的黄色链接）：
:root {
–main-color: #2c3e50;
–primary: #3498db;
–secondary: #e67e22;
–entry: #ffffff;
–theme: #f8f9fa;
–code-bg: #f5f6fa;
}
.entry-header h1 a,
.post-title a {
color: #2c3e50 !important;
}
修改文章字体颜色 在 custom.css 中追加：
.post-content p, .post-content li {
color: #333333;
}
配置首页固定欢迎语 在 hugo.toml 的 [params] 下添加：
[params.homeInfoParams]
Title = “👋 欢迎来到我的博客”
Content = “这里记录了我的学习与思考。”
添加导航菜单外部链接
[[menu.main]]
name = “友链”
url = “https://aaacoo.xyz/"
weight = 6
修改网站底部版权 在 hugo.toml 的 [params] 中添加：
footer = “© 2026 你的名字 · 由 Hugo & PaperMod 驱动”
八、搜索功能调试
如果配置正确但搜索图标不出现，请检查：
hugo.toml 中 ShowSearch = true 且 [outputs] 包含 JSON。
执行 hugo 后，确认 public/index.json 文件存在。
在浏览器中清空缓存并硬性重新加载（Ctrl+F5 或开发者工具停用缓存）。
如果页面源码里没有 search-toggle，可强制注入：
mkdir -p /var/www/techblog/layouts/partials
nano /var/www/techblog/layouts/partials/extend_head.html
写入搜索框 HTML（详见对话历史），再次生成。
九、评论系统
在 GitHub 新建一个公开仓库（如 blog-comments），安装 Utterances App 并授权该仓库。 配置文件中 [params.utterances] 部分填写真实仓库名，生成后文章底部即出现评论区。
十、常见错误与解决
can’t evaluate field enabled in type bool 检查 [params.math] 是否误写成了 [[params.math]]，或者是否在某处写了 math = true 覆盖了表格。使用单括号，并确保没有重复的布尔键。
TOML 重复键错误 删除文件顶部多余的 author、title 等，让它们只存在于 [params] 下。用 grep -n “keyword” hugo.toml 查找重复。
hugo new 报错找不到目录 手动创建 content/posts 目录：mkdir -p content/posts。
FileBrowser 重启后密码失效 启动时必须用 -d 指定固定的数据库文件，并注册为系统服务。
网站无法访问（连接超时） 检查云安全组是否放行 80 端口，服务器防火墙是否拦截。
结语 至此，一个具备在线编辑能力、美观且功能齐全的技术博客就搭建完成了。后续你只需要通过 FileBrowser 后台写作，然后在终端执行 hugo 即可更新站点。如果将来绑定域名并启用 HTTPS，只需修改 baseURL 并用 Certbot 配置 Nginx 即可。
希望这篇教程对你有所帮助，欢迎在评论区交流！