Hugo 博客部署到 GitHub Pages 完全指南

Sat, 13 Jun 2026 00:00:00 +0000

本篇从一个已经能运行 hugo --minify 的博客开始。还没有站点，可以先完成 Hugo 与 IMX 入门指南；需要调整主题细节，参见 IMX 主题配置指南。

1. 确认仓库与站点地址

GitHub Pages 有两种常见地址，baseURL 必须与最终公开地址对应：

类型	仓库名	`baseURL`
用户站点	`your-name.github.io`	`https://your-name.github.io/`
项目站点	`my-blog`	`https://your-name.github.io/my-blog/`

本站是用户站点，但使用自定义域名，所以 hugo.toml 中写的是 baseURL = 'https://blog.cxx.pub/'。项目站点尤其要保留末尾的仓库路径；否则页面链接、图片或样式可能指向错误位置。

在发布前检查本地环境与构建：

hugo version
go version
hugo --minify

IMX 需要 Hugo Extended 和 Go。Hugo Module 的依赖应记录在 go.mod、go.sum，并连同 hugo.toml 一起提交。将 /public/、/resources/_gen/、/.hugo_build.lock 放入 .gitignore；Pages 工作流会构建 public/，不必把它提交进源码仓库。

2. 创建 GitHub 仓库

在 GitHub 新建仓库。若希望使用根地址 https://your-name.github.io/，仓库名必须是 your-name.github.io；若使用项目地址，可以取普通仓库名。已有本地 Git 仓库时，建议创建空仓库，避免首次推送出现不必要的历史合并。

然后在仓库 Settings → Pages → Build and deployment → Source 选择 GitHub Actions。本文的工作流会上传构建产物并部署，不使用“从分支发布”的方式。

GitHub Pages on IMX-博客

Hugo 博客部署到 GitHub Pages 完全指南

1. 确认仓库与站点地址

2. 创建 GitHub 仓库