# Hugo From Zero to Production Tutorial

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

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

---

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

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

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

```bash
# 下载 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 扩展版

```bash
# 安装 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 站点

```bash
# 创建项目目录（可自定义路径）
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. 下载主题

```bash
# 进入项目目录
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. 启用主题

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

---

## 四、基础配置（hugo.toml）

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

```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 }}`
> 

---

## 五、添加测试文章

```bash
# 创建一篇测试文章
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 不中断时使用）

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

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

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

```bash
# 创建服务文件
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
```

启动并设置开机自启：

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

---

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

### 1. 生成静态文件

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

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

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

```bash
# 复制静态文件到 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 ../../` |

---

## 九、故障排查

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

---

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