让 Codex 修好网站死链：从复现到回归检查

适合维护文档站、博客和产品网站的人。你不需要先学会写爬虫；这篇要教的是：把“页面打不开”交给 Codex 时，如何让它找到原始链接、只改需要改的地方，并留下可重复执行的检查。

可以带走：三段可复制任务描述、一套运行命令，以及判断修复是否完成的方法。 本文使用本站公开维护记录和现有检查器；不是一次虚构的客户项目，也没有统计节省了多少时间。

真实问题：构建成功，读者还是会遇到 404

2026-09-27，本站第 05 章中三个 /advanced/*.html 入口实际返回 404，修订后改为可访问的目标。次日增加了渲染后站内链接检查，并接入质量 CI。过程见 09-27 记录、检查器提交 872bbd0。

这个问题容易漏掉：构建能生成 HTML，不代表 HTML 中每个链接都存在；源 Markdown 里还有原始 HTML 链接，只搜索 Markdown 链接语法也可能遗漏。

这里的经验是先检查用户实际打开的页面，再回到源文件定位。不要为了消除一个 404 就批量改 URL 或加一个指向首页的跳转，那样可能掩盖内容真的缺失。

技巧一：交代失败现场，让 Codex 少猜一步

把下面模板中的方括号换成你的实际信息；不确定就写“未知”，不要填猜测路径。

我在维护这个网站，有一个站内链接打不开。
来源页面：[从哪个页面点击]
链接文字：[看到的按钮或文字]
目标地址：[实际跳转 URL]
实际结果：[404 / 超时 / 其他现象]
预期结果：[本来应该打开的内容]

先读取仓库说明、路由和内容组织方式，只读定位：
1. 复现请求，分清真实 404、网络失败和需要登录。
2. 找到生成这个链接的源文件，说明是否还有相同引用。
3. 找出合理的现有目标；无法确定时列出缺失信息。
给我源文件、失败证据和最小修复方案，先不修改文件。

官方 Prompting 的 Fix a bug 建议提供复现步骤、相关文件、约束和验证方式。这里的中文模板是本站针对链接维护改写的方法，不是保证一次修好的“万能提示词”。

技巧二：限定修复范围，但保留发现问题的空间

确认目标内容后再继续：

按刚才确认的方案修复这个链接。
保留现有公开 URL，只修改错误引用；不要顺手改样式、依赖或无关文章。
检查 Markdown 和原始 HTML 中的同类引用。
如果目标文章不存在或方案会影响其他页面，先说明，不用删除入口掩盖问题。
修复后重跑原始失败请求和现有相关检查，列出改动文件及 diff。
本轮不提交、不推送、不部署，先把可审查的结果交给我。

本例采用了“修正文案中的入口，再检查渲染结果”的路线。其他仓库可能是路由、大小写或部署前缀问题，不能照抄目标路径。限定的是变更范围，而不是预先指定一个尚未验证的根因。

技巧三：验收时检查行为，而不只看总结

可以直接用本仓库体验检查流程。前提是 Git、Node.js 20.9+、npm 和 Python 3.9+ 已可用，终端位于一个你允许新建练习目录的位置；若同名目录存在，换名字，避免覆盖已有工作。

git clone https://github.com/modelsell/codex-study-club.git codex-link-practice
cd codex-link-practice
npm ci
npm run test:links
npm run lint
npm run build
npm run start -- --hostname 127.0.0.1 --port 3107

最后一条会持续运行服务器。另开终端，进入同一个 codex-link-practice 目录：

python3 scripts/check_internal_links.py --base-url http://127.0.0.1:3107
git diff --check
git diff --stat

完成后在服务所在终端按 Ctrl+C 关闭。此仓库的 npm run check:links 默认也是 3107；端口已占用时，为启动和检查命令同时换一个端口，不关闭不明进程。普通站点检查不需要模型 API Key；你让 Codex 执行任务时，其用量仍受所用账号或服务规则影响。

两个“通过”各自意味着什么

检查	应看到什么	不能证明什么
npm run test:links	3 项检查器测试通过，含正常链接、人为断链和网络异常分类	不是当前站点没有断链的结论
check_internal_links.py	当前本地构建的页面和目标数量，以及 0 failures	不是生产站点已部署，也不是外部链接、图片和锚点都有效

现有回归测试会在临时本地服务器里加入一个不存在的链接，确认检查器报告 404 并返回退出码 1；测试套件最终通过，表示它成功识别了故障。这是人为测试夹具，不是今天生产网站仍存在该故障。

检查器退出码：0 为本轮检查通过，1 为发现失败目标，2 为准备条件错误（如本地服务没启动或 Sitemap 无效）。它仅接受本机 HTTP 服务，不用于扫描任意外部站点。

将结果交给 Codex 时，可以继续用：

请根据实际命令输出交付验收记录：
原始链接现在返回什么，正文是否是预期内容？
检查覆盖了哪些页面，哪些范围没有覆盖？
区分内容断链、网络失败、检查环境未准备好。
不把删测试、忽略错误或改成永远成功当作修复。
如果本地通过，只写本地通过；没有部署证据，不写已上线。

遇到这些情况，下一步怎么做

• 命令说 Sitemap 不可用： 先确认构建完成、服务端口一致，别让 Codex 在服务没启动时改业务代码。
• 出现 NETWORK： 保留错误分类，确认服务是否仍在运行；不要把网络异常批量替换成链接错误。
• 检查成功但点击仍不对： 看正文和交互，200 也可能返回错误页面；再确认你验收的是本地还是生产环境。
• 想接入自己的 CI： 参考本站质量工作流中启动本地服务、等待就绪、执行检查和清理进程的步骤。先适配你的路由及 Sitemap，再接入，不必另外开启机器人写权限。

来源与验证范围

核对日期：2026-10-05。产品方法依据当日读取的 OpenAI Prompting；历史事实依据上述公开记录和提交。检查实现为脚本及回归测试。

本次重新运行现有回归测试和本站本地构建检查；未重新制造生产 404，也未在读者仓库重演模板对话。模板可供迁移使用，不保证其他项目无需适配。读者可继续查看任务设计、任务执行与完成但未验证的排查方法。