博客修复与自动化部署工作记录

本文记录 2026-07-30 对博客工程（goodniuniu.github.io）的一次集中分析与修复，提交 aeb3ffa，已通过 GitHub Actions 自动部署上线。

一、发现的问题

1. 标签全部失效：17 篇文章的 front-matter 写成 - # Thought，YAML 中 # 是注释符，实际解析为空标签，标签页为空。
2. 草稿混入发布目录：未完成的《关于写作的准备》放在 _posts/ 下，会被发布到线上。
3. 文档过期：README 仍写”部署到 master 分支”，与已切换的 gh-pages 部署方式不一致。
4. 模板缺字段：scaffolds/post.md 没有 slug / categories，与写作约定不符。
5. 65 处本地改动未提交，云端部署感知不到。

二、修复措施

• 批量修正 17 篇文章的 tags 写法，另修正一处拼写 Thougt → Thought；本地 hexo generate 验证，8 个标签页（Book / Books / Digest / Listening / Pic / Practice / Reading / Thought）正确生成。
• 草稿移入 source/_drafts/，不再发布；本地预览草稿可用 hexo server --draft。
• 文章模板补充 slug 和 categories 字段。
• README 更正为 gh-pages 部署说明，补充草稿目录与回滚方式（在 source 分支 revert 后重新推送，不要依赖 gh-pages 的历史）。
• 全部改动提交并推送 source 分支，Actions 约 20 秒完成构建发布。

三、后续写作流程

1. 在 source/_posts/ 新建 YYYYMMDD-标题.md，front-matter 写 title / slug / date / categories / tags（tags 不要加 # 号）。
2. git add → git commit → git push，推送即自动发布，无需本地安装 Node/Hexo。
3. 草稿放 source/_drafts/，写完移回 _posts/ 再推送。
4. 可选本地预览：npx hexo server，访问 http://localhost:4000。

四、经验

• front-matter 是 YAML，特殊字符（#、: 等）有语法含义，写标签、标题时要留意，必要时加引号。
• “源码分支 + 自动构建产物分支”的双分支结构下，文档必须跟着部署方式同步更新，否则会误导后续操作。
• 修复后先用本地构建验证产物（标签页、草稿是否排除），再推送上线，比上线后返工省事。