Hugo From Zero to Production Tutorial

2026-06-11 约 1865 字预计阅读 4 分钟

Hugo 全栈教程：从环境安装到生产发布（含自启动、备案适配）

适配系统：腾讯云 TencentOS/CentOS 7+ | Hugo 版本：v0.163.0+ 扩展版 | 主题：Even

一、环境准备：安装 Hugo 扩展版

Hugo 扩展版才支持 SCSS 编译，主题样式才能正常显示，必须装带 extended 的版本。

1. 安装 Go 环境（Hugo 编译依赖）

        
        
        
    
# 下载 Go 1.26.4（Hugo v0.163.0 要求 Go ≥ 1.26）
cd /tmp
wget https://golang.google.cn/dl/go1.26.4.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.26.4.linux-amd64.tar.gz

# 配置环境变量（永久生效）
echo 'export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin' >> ~/.bashrc
echo 'export GOPATH=$HOME/go' >> ~/.bashrc
source ~/.bashrc

# 验证 Go 安装
go version  # 输出 go version go1.26.4 linux/amd64 即成功

2. 安装 Hugo 扩展版

        
        
        
    
# 安装 CGO 依赖（编译 Hugo 必须）
sudo yum install -y gcc gcc-c++ make
# 验证 GCC 版本 ≥ 10（Go 1.26 要求）
gcc --version
# 如果版本 < 10，执行下面升级（CentOS 7）：
sudo yum install -y centos-release-scl
sudo yum install -y devtoolset-10
scl enable devtoolset-10 bash

# 编译安装 Hugo 扩展版
CGO_ENABLED=1 go install -v -tags extended github.com/gohugoio/hugo@v0.163.0
# 移动到系统 PATH
sudo mv ~/go/bin/hugo /usr/local/bin/
# 验证安装（必须带 +extended）
hugo version  # 输出 hugo v0.163.0+extended linux/amd64 即成功

二、创建 Hugo 站点

        
        
        
    
# 创建项目目录（可自定义路径）
mkdir -p /data/hugo
cd /data/hugo
# 初始化 Hugo 站点
hugo new site .
# 输出 Congratulations! Your new Hugo site is created in /data/hugo. 即成功

三、安装主题（以 Even 主题为例）

Even 是简洁技术博客主题，若需更活跃维护的主题可替换为 LoveIt / PaperMod

1. 下载主题

        
# 进入项目目录
cd /data/hugo
# 克隆 Even 主题（国内慢用 Gitee 镜像：https://gitee.com/mirrors/hugo-theme-even）
git init
git submodule add https://github.com/olOwOlo/hugo-theme-even.git themes/even

2. 启用主题

        
# 写入主题配置到 hugo.toml
echo "theme = 'even'" >> hugo.toml

四、基础配置（hugo.toml）

编辑项目根目录的 hugo.toml，替换为以下配置（适配备案+中文环境）：

        
        
        
    
baseURL = 'https://blog.geluli.cn'  # 备案后填域名，未备案填 http://服务器公网IP
languageCode = 'zh-CN'
title = '我的 Hugo 站点'
theme = 'even'

[params]
  subtitle = '分享技术，记录生活'
  # 头像路径（图片放 static/uploads/avatar.png）
  avatar = 'uploads/avatar.png'
  # 暗黑模式
  darkMode = true
  # 代码高亮
  highlight = true
  # 工信部备案号（备案后填写，未备案可注释）
  beianIcp = '粤ICP备12345678号-1'
  # 公安备案号（可选）
  beianGongan = '粤公网安备 12345678901234号'

[params.Author]
  name = '你的名字'
  email = '你的邮箱@example.com'
  link = 'https://blog.geluli.cn'

# 菜单配置
[[menu.main]]
  identifier = "home"
  name = "首页"
  url = "/"
  weight = 1

[[menu.main]]
  identifier = "posts"
  name = "归档"
  url = "/posts/"
  weight = 2

[[menu.main]]
  identifier = "tags"
  name = "标签"
  url = "/tags/"
  weight = 3

📌 若使用 2021 年前的旧版 Even 主题，修复 Author 报错：

编辑 themes/even/layouts/partials/head.html，把 {{ .Site.Params.Author.name }} 改为 {{ .Site.Params.Author.name | default .Site.Params.author }}

五、添加测试文章

        
        
        
    
# 创建一篇测试文章
hugo new posts/hello-hugo.md
# 编辑文章，把 draft: true 改为 draft: false（否则不显示）
sed -i 's/draft: true/draft: false/' content/posts/hello-hugo.md
# 可选：添加头像
mkdir -p static/uploads
# 放一张 avatar.png 到 static/uploads/ 目录

六、本地预览与调试

1. 临时预览（SSH 不中断时使用）

        
cd /data/hugo
# 启动预览，绑定所有网卡，外网可访问
hugo server -D --bind=0.0.0.0 --port=1313 &
# 浏览器访问：http://服务器公网IP:1313
# 停止预览：pkill -f "hugo server"

2. 长期后台运行（推荐：systemd 托管）

避免 SSH 断连导致服务停止，配置系统服务：

        
# 创建服务文件
sudo vi /etc/systemd/system/hugo.service

写入以下内容（替换路径为用户实际路径）：

[Unit]
Description=Hugo Preview Server
After=network.target

[Service]
Type=simple
WorkingDirectory=/data/hugo
ExecStart=/usr/local/bin/hugo server -D --bind=0.0.0.0 --port=1313
Restart=always
User=root

[Install]
WantedBy=multi-user.target

启动并设置开机自启：

        
        
        
    
sudo systemctl daemon-reload
sudo systemctl start hugo
sudo systemctl enable hugo
# 查看运行状态（显示 active (running) 即成功）
sudo systemctl status hugo
# 查看日志
journalctl -u hugo -f

七、生产环境发布（适配备案+反向代理）

1. 生成静态文件

        
        
        
    
cd /data/hugo
# 清理旧缓存
rm -rf public resources
# 生成静态文件（自动替换 baseURL 为配置的域名/IP）
hugo
# 生成的静态文件全部在 public/ 目录下

2. 部署到 Nginx（配合反向代理）

假设你的 Nginx 静态目录为 /var/www/html/hugo，反向代理已配置 blog.geluli.cn 指向该目录：

        
        
        
    
# 复制静态文件到 Nginx 目录
sudo mkdir -p /var/www/html/hugo
sudo cp -r public/* /var/www/html/hugo/
# 设置权限
sudo chown -R nginx:nginx /var/www/html/hugo
# 重启 Nginx
sudo systemctl restart nginx

3. 备案适配说明

若域名已完成腾讯云接入备案：直接访问 https://blog.geluli.cn，footer 会自动显示备案号，符合合规要求。
若未完成接入备案：临时把 hugo.toml 的 baseURL 改为 http://服务器公网IP，用 IP 访问，备案完成后再改回域名。

八、常用命令速查

操作	命令
创建新文章	`hugo new posts/文章名.md`
本地预览	`hugo server -D --bind=0.0.0.0 --port=1313`
生成静态文件	`hugo`
清理缓存	`rm -rf public resources`
重启 Hugo 服务	`sudo systemctl restart hugo`
查看 Hugo 版本	`hugo version`
更新主题	`cd themes/even && git pull && cd ../../`

九、故障排查

样式丢失：执行 rm -rf public resources 清理缓存后重新 hugo。
文章不显示：检查文章内 draft: false，执行 sed -i 's/draft: true/draft: false/' content/posts/*.md。
端口被占用：更换端口 hugo server -D --port=1314。
编译报错：升级 GCC 到 10+，执行 scl enable devtoolset-10 bash 后再编译。

按照以上步骤操作，即可完成从 Hugo 安装、主题配置、预览到生产发布的全流程，未备案阶段用 IP 测试，备案完成后切域名即可正常访问 🎉