25 部署疑难排查（实战案例）

案例 1：根路径 200，但 /en/opencode/ 是 404

症状

• https://opencode-handbook-zh.pages.dev 返回 200
• https://opencode-handbook-zh.pages.dev/en/opencode/ 返回 404

根因

• VitePress 未配置 locales 或英文页面目录未创建。

修复

1. 在 docs/.vitepress/config.mts 增加 locales.root + locales.en。
2. 补齐 docs/en/opencode/*.md 最小页面集合。
3. 重新构建并部署。

验收

• / 与 /en/opencode/ 均返回 200。

---

案例 2：仓库里有 workflow，实际上没自动部署

症状

• .github/workflows/deploy-pages.yml 已存在，但推送后没有发布。

根因

• GitHub Secrets 未配置：CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID。
• 或 Token 权限不足（Pages Edit / Account Read）。

修复

• 在仓库 Settings → Secrets and variables → Actions 中补齐 secrets。
• 重新触发 workflow_dispatch。

---

案例 3：链接巡检误报过多

症状

• 每周 link-check 大量失败，但多为临时网络抖动。

根因

• 外链波动 + 重试策略不足。

修复

• 增加重试次数、超时时间。
• 对高波动域名设置临时排除（并在文档注明原因）。
• 告警 issue 复用同一条，避免噪音泛滥。

---

案例 4：部署成功但页面没变化

症状

• Workflow 成功，页面内容仍像旧版。

根因

• 构建目录错误（不是 docs/.vitepress/dist）。
• 部署分支标识与预期不一致。

修复

• 固化构建输出目录。
• 在 workflow 输出部署 URL 并做 smoke 检查。

---

一键排查顺序（建议）

1. 看 workflow 日志：是否真执行到 deploy。
2. 看输出目录：是否是 docs/.vitepress/dist。
3. 看路由：/、/opencode/、/en/opencode/ 状态码。
4. 看 secrets 权限与值是否存在。
5. 手动 workflow_dispatch 复现并比对 URL。