Hexo 的发布问题往往不是“页面突然坏了”，而是流程中的某一步没有被确认：文章没有通过 Front Matter 检查，构建没有生成目标页面，部署同步到了错误目录，或者线上缓存仍然显示旧内容。排障的关键不是马上重跑所有命令，而是先确定问题发生在哪一层。

我把发布过程固定成四个阶段：检查源文件，构建 public/，演练同步范围，最后验证线上页面。

第一层：先检查源文件

发布前先运行仓库检查：

pwsh ./ops/check.ps1

如果这里失败，先不要构建。常见原因包括文章缺少 title、date、tags、categories 或 description，或者仓库关键目录被误删。Front Matter 错误应回到 Markdown 文件修复，不要用生成后的 HTML 反向补救。

YAML 报错时，先看最近修改的几行，尤其是列表缩进、冒号和 Tab。可以把文章暂时缩小到最小 front matter，再逐步加回字段，快速定位是字段名问题还是值的格式问题。

第二层：确认生成物

检查通过后，使用仓库的 Docker 构建入口：

pwsh ./ops/build.ps1

这个脚本会清理旧的 public/，再生成新的静态页面。构建成功后，不要只看命令最后一行；确认目标文章的 index.html 真的存在：

Test-Path public/2026/07/31/hexo-local-writing-preview/index.html
Test-Path public/2026/07/31/hexo-front-matter-guide/index.html
Test-Path public/2026/07/31/hexo-assets-and-links/index.html
Test-Path public/2026/07/31/hexo-build-deploy-troubleshooting/index.html

如果本机没有 Docker，可以使用 npm 兜底：

pwsh ./ops/build.ps1 -Mode npm

兜底模式需要记录 Node 和 npm 版本。两种模式的验收标准相同：public/ 中有正确页面，页面标题和站内链接已渲染。

第三层：区分内容错误和主题错误

如果文章页面没有生成，优先检查文件名、draft、date 和 Front Matter。若页面生成了但样式或代码块异常，再检查主题配置和 Markdown 结构。

不要一遇到渲染问题就直接编辑 themes/butterfly。正常定制应放在根目录配置；只有确定是上游主题行为时，才单独记录版本和变更范围。把内容问题和主题问题分开，排查速度会快很多。

资源问题也可以在 public/ 中定位。文章里的图片引用已经写进 HTML，但对应文件不存在，通常是资源路径或构建复制范围的问题。先确认 source/images 或文章资源目录，再检查生成结果。

第四层：部署前先 dry-run

构建通过后，先演练部署：

pwsh ./ops/deploy.ps1 -DryRun

重点看终端输出的目标主机、端口、目标用户和站点目录。dry-run 不覆盖远端文件，它的价值是让你在同步发生前发现目标错误。

确认目标正确后再执行正式部署：

pwsh ./ops/deploy.ps1

当前脚本优先使用 rsync；没有 rsync 时会使用 tar、scp 和 ssh 兜底。无论哪条路径，都不要跳过 dry-run。部署失败时保留完整错误输出，区分本地 public/、SSH 连接、远端目录权限和网络问题。

发布后要做 HTTP 验证

部署命令成功只说明文件同步完成，不等于用户已经看到正确页面。可以用 PowerShell 逐个检查：

$urls = @(
  "https://dreamjia.cloud/",
  "https://dreamjia.cloud/2026/07/31/hexo-local-writing-preview/",
  "https://dreamjia.cloud/2026/07/31/hexo-front-matter-guide/",
  "https://dreamjia.cloud/2026/07/31/hexo-assets-and-links/",
  "https://dreamjia.cloud/2026/07/31/hexo-build-deploy-troubleshooting/"
)
foreach ($url in $urls) {
  $response = Invoke-WebRequest -Uri $url -UseBasicParsing
  Write-Output "$($response.StatusCode) $url"
}

状态码正常后，再检查页面标题、最新文章列表、分类页和标签页。如果只有部分页面更新，先比较本地 public/ 和远端同步结果，不要立即重复覆盖式部署。

安全回滚而不是重置现场

如果新版本确实需要回滚，使用上一份已验证的 Git 提交重新构建，先 dry-run，再部署。不要为了“清理干净”运行 git reset –hard，也不要删除不知道来源的工作树修改。

最有用的发布记录至少包含提交哈希、构建模式、dry-run 结果和线上验证结果。记录越清楚，回滚越像一次普通发布，而不是一次临时抢修。

更多目标目录、环境变量和交接约定可以查看 docs/05-构建与部署.md 与 docs/15-博客内容发布交接文档.md。

小结

Hexo 排障可以按一条固定路径进行：check 挡住结构错误，build 确认生成物，dry-run 确认同步范围，HTTP 验证确认用户看到的页面。每一步只回答一个问题，就不必把所有可能性同时塞进脑子。

如果你刚开始写作，可以先读本地写作与预览；想理解元数据和资源组织，再看Front Matter 指南与资源和站内链接指南。