Hugo 是世界上最快的静态网站生成器之一。它使用 Go 语言编写，可以在毫秒级完成整个网站的构建，并且原生支持 Markdown 内容格式。

为什么选择 Hugo？

  • 构建速度快 —— 数百篇文章也能在一秒内完成编译。
  • 原生 Markdown —— 内容永远可以迁移，不被平台绑定。
  • 内置多语言支持 —— 非常适合像本站这样的双语网站。
  • 无需数据库和运行时服务器 —— 产物是纯静态 HTML，完美契合 Cloudflare Pages。

安装 Hugo

在 macOS 上可以通过 Homebrew 安装 Hugo Extended：

bash 
brew install hugo
hugo version

创建新站点

bash 
hugo new site jeiii-codes
cd jeiii-codes
hugo server

打开 http://localhost:1313 即可本地预览网站。

撰写第一篇文章

bash 
hugo new content posts/my-first-post.zh-cn.md

然后编辑 Markdown 文件，将 draft 设为 false 并保存，Hugo 会自动刷新页面。

构建生产版本

bash 
hugo --minify

生成的网站位于 public/ 目录，可以直接部署到 Cloudflare Pages。

部署到 Cloudflare Pages

Cloudflare Pages 可以连接 Git 仓库，在每次推送时自动运行 Hugo 构建，并将生成的静态文件发布到全球网络。

1. 将项目推送到 GitHub

如果项目还没有纳入 Git 仓库：

bash 
git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/<你的账号>/<你的仓库>.git
git push -u origin main

2. 创建 Pages 项目

  1. 登录 Cloudflare 控制台，进入 Workers & Pages。
  2. 选择 Create → Pages → Connect to Git。
  3. 选择你的仓库和 main 分支。
  4. 按下表填写构建配置：
配置项 值
Framework preset Hugo
Production branch main
Build command hugo --minify
Build output directory public
Root directory /（或 hugo.yaml 所在目录）

3. 固定 Hugo 版本

Cloudflare 构建环境自带的 Hugo 版本可能与本机不同。通过环境变量显式固定版本，才能保证本地与线上构建结果一致。

进入 Pages 项目的 Settings → Environment variables，在 Production（如果使用预览部署，也建议添加到 Preview）中新增以下变量并保存：

变量名 值
HUGO_VERSION 0.169.0

本项目使用 Hugo Extended v0.169.0 开发，因此 Cloudflare Pages 也固定使用同一版本。可以在本地通过以下命令确认版本：

bash 
hugo version

如果 Cloudflare 暂不支持该精确版本，可以选择最接近的可用版本，或在自定义构建步骤中安装所需的 Hugo 二进制文件。

4. 部署

点击 Save and Deploy。Cloudflare 会执行 hugo --minify 并发布 public/ 目录。此后每次推送到 main 都会触发新的生产部署，Pull Request 则会生成独立的预览地址。

5. 绑定自定义域名

  1. 进入 Pages 项目的 Custom domains → Set up a custom domain。
  2. 输入域名，例如 code.example.com，按提示完成 DNS 配置。
  3. 将 hugo.yaml 中的 baseURL 修改为最终域名：
yaml 
baseURL: "https://code.example.com/"
  1. 提交并推送修改。这样可以保证 canonical、sitemap.xml、RSS 与 Open Graph 链接全部指向正式域名。

本站即采用 HUGO_VERSION=0.169.0 构建，正式域名为 https://code.jeiii.us/。