GitHub Pages 部署前检查清单

Mon, 18 May 2026 09:20:00 +0800

配置检查

部署前先确认 hugo.toml 中的站点地址、语言、标题和分页配置。baseURL 会影响线上资源路径，尤其是样式和图片。

如果使用 GitHub Pages 的用户站点，常见地址是：

baseURL = "https://username.github.io/"

如果使用项目站点，则通常需要带上仓库名。

发布前至少检查这些内容：

GitHub 仓库的 Pages Source 需要选择 GitHub Actions。工作流构建时要安装 Hugo Extended，并上传 public 目录作为 Pages artifact。

常用构建命令是：

hugo --gc --minify

部署问题通常不是 Hugo 本身复杂，而是路径、草稿状态、Actions 权限和 Pages 设置容易漏。上线前做一次清单检查，可以省掉很多排查时间。

Mon, 18 May 2026 09:00:00 +0800

我希望博客能长期维护，文章源文件可以直接用 Git 管理，部署流程尽量简单，所以选择了 Hugo、Markdown 和 GitHub Pages。

这一套方案的核心好处是：文章就是普通 Markdown 文件，构建结果是静态页面，不依赖数据库，也方便以后迁移。

第一版不追求复杂功能，先完成几个基础能力：

当前项目采用 Hugo 标准结构：

content/ # 页面和文章
layouts/ # 自定义模板
assets/ # Hugo 处理的 CSS
static/ # 原样复制的图片和图标

没有引入外部主题，主要是为了减少初始依赖。等站点稳定后，再决定是否接入主题或继续维护自定义模板。

写文章时先使用草稿状态：

hugo new content posts/my-new-post.md
hugo server -D

确认内容、图片、链接和排版都没问题后，再把 draft 改为 false，提交并推送到 GitHub。

个人博客最重要的不是功能复杂，而是能稳定写、稳定发布、稳定维护。先让系统跑起来，再逐步加入搜索、评论、统计和自定义域名。