上线不是部署命令返回成功的那一刻，而是读者能够打开正确页面、站内链接没有断、下一位维护者知道这次改了什么之后，才算真正结束。

Hexo 是静态站点，回滚看起来比动态服务简单，但它同样需要边界：哪一个提交是已验证的版本，哪一份 public/ 是由它生成，远端同步是否经过 dry-run，以及当前工作树有没有不能被覆盖的修改。

发布前先留下边界

开始前先看工作树：

git status --short --branch

如果有未提交修改，先确认它们属于当前任务还是之前留下的工作。内容发布时只暂存本次文章和文档，不用 git add . 把未知文件一起加入。

提交前再看暂存区：

git diff --cached --name-status

一个清楚的提交边界，就是未来最便宜的回滚点。提交信息也应当说明它包含什么，例如“新增文章”或“更新主题配置”，不要把内容、依赖和服务器脚本混在一个模糊的提交里。

用固定顺序发布

当前仓库的发布顺序是：

pwsh ./ops/check.ps1
pwsh ./ops/build.ps1
pwsh ./ops/deploy.ps1 -DryRun
pwsh ./ops/deploy.ps1

第一步检查文章和仓库结构。第二步使用 Docker 生成 public/。第三步只演练同步目标和文件范围。前面三步都通过后，最后一步才接触远端站点。

如果 Docker 暂时不可用，可以按交接文档使用 npm 兜底，但要记录 Node 和 npm 版本。构建模式可以不同，验收标准不能不同：目标页面必须在 public/ 中生成。

发布后验证不要省

部署命令成功后，至少检查首页、最新文章、分类页和标签页。新文章还要确认：

  1. URL 能返回页面；
  2. 页面标题与 front matter 一致；
  3. 图片、代码块和站内链接已渲染；
  4. 相关旧文章能通过链接找到它；
  5. 线上页面不是构建前的旧版本。

可以用 PowerShell 快速检查公开页面：

$urls = @(
  "https://dreamjia.cloud/",
  "https://dreamjia.cloud/2026/08/08/hexo-performance-optimization/",
  "https://dreamjia.cloud/2026/08/08/hexo-seo-and-sitemap/",
  "https://dreamjia.cloud/2026/08/08/butterfly-configuration-tips/",
  "https://dreamjia.cloud/2026/08/08/hexo-maintenance-and-rollback/"
)
foreach ($url in $urls) {
  $response = Invoke-WebRequest -Uri $url -UseBasicParsing
  Write-Output "$($response.StatusCode) $url"
}

这段检查不能替代浏览器视觉检查，却能先确认服务器返回了正确状态。

把故障分成几层

如果 check 失败，问题在源文件或文章元数据，先修 Markdown 和 front matter。

如果 build 失败，问题通常在 YAML、Markdown 渲染、主题配置或依赖环境。保留完整日志，确认是 Docker、Node 还是某篇文章触发了错误。

如果 dry-run 失败，先检查 public/、目标主机、端口和环境变量，不要直接执行正式同步。

如果正式部署失败，区分网络、SSH、远端目录权限和本地生成物问题。原因不明时不要连续重复覆盖式部署，先保留错误输出。

这种分层的价值是让每次只处理一个问题。不要因为页面打不开，就同时改文章、主题和服务器配置。

一条安全的回滚路径

需要回滚时，先找到上一份已经验证过的 Git 提交：

git log --oneline --decorate -10

确认目标提交后，在干净或可解释的工作状态下重新生成 public/：

pwsh ./ops/build.ps1
pwsh ./ops/deploy.ps1 -DryRun
pwsh ./ops/deploy.ps1

回滚的目标是恢复站点到一个已知状态，不是清空开发现场。不要使用 git reset –hard 覆盖未知工作树修改，也不要删除与当前任务无关的文件。

如果只是某篇文章有问题，优先修正文章并提交一个小修复；只有页面结构或整批发布确实需要恢复时，才回到上一份完整提交。

发布记录应该留下什么

每次发布至少记录：

  • 提交哈希和分支；
  • 构建模式和命令结果；
  • dry-run 是否通过；
  • 正式部署的时间；
  • 首页和新文章 URL 的验证结果；
  • 是否存在未提交的既有修改。

这些信息足够让下一位维护者复现过程，也足够在出现问题时快速定位差异。记录不需要很长，但不能只写“已经发布”。

更多目标目录、变量和交接步骤可以查看 docs/06-运维与回滚.md 与 docs/15-博客内容发布交接文档.md。

小结

稳定的 Hexo 发布流程不是把每次上线变成仪式，而是让它拥有清晰的前后边界：发布前知道提交了什么，发布中知道同步到哪里，发布后知道页面是否正确，出问题时知道回到哪个已验证版本。

如果你想先优化构建和资源，可以阅读Hexo 性能优化；SEO 和 URL 见站点地图指南，主题定制见Butterfly 配置技巧。