一次 404 排查复盘：Google 说我的网站有死链，最后发现"凶手"是我自己的文档

摘要：收到 Google Search Console 的索引报告，说我的静态站有一个 404。我把全站 29 个 URL 翻了个底朝天，一个死链都没找到——最后发现，出问题的地址，是我的协议文档和 DOI 档案记录里白纸黑字引用的。这篇文章记录完整的排查过程，以及静态站维护者值得带走的三条经验。

背景

我维护一个开源项目 EcoCompute（LLM 推理能耗实测），官网是一个纯静态站：GitHub Pages + Jekyll，挂自定义域 quantenergy.tech。内容不多——首页、估算器、文档、博客，加上 changelog，sitemap 里一共 29 个 URL。

网站上线一段时间后，某天收到 Google Search Console 的邮件，提示索引覆盖有问题。打开一看，报告分四类：

静态站维护者看到这种邮件的第一反应通常是"哪根链接断了"。我的第一反应是：先别急着修，先把四类报告分清楚。

第一步：分类——四类里三类不用管

• 备用网页（有规范标记）：Google 自己都标注了"有适当的规范标记"。这是 /blog 和 /blog/ 这类重复 URL 被 canonical 收敛后的正常状态，不是错误。
• 已发现/已抓取 - 尚未编入索引：小站常态。页面新、内链稀疏，Google 有意压后处理。sitemap 和 robots.txt 都健康的情况下，随时间自然收录，强行"优化"反而容易动作变形。
• 未找到 (404)：唯一的真问题。

但这里有个信息差：404 的具体 URL 只在 GSC 页面里能看到，邮件里没有。于是我先做能做的——全站扫描。

第二步：全站扫描，一无所获

方法很朴素：把 sitemap 声明的全部 URL 拉出来，逐一实测状态码，再和仓库里的实际文件对照：

对照结果：29 个 URL，对应文件全部存在；实测能建立连接的全部返回 200，包括博客文章的无后缀 clean-URL 格式（Jekyll 的目录重写正常工作）。

排查中间还有个小插曲：一批请求返回 000（连接层失败）。这不是 404，是网络抖动造成的假象——区分方法很简单，带重试再跑一遍，或者换对照（当时我这边是代理对目标域抽风，百度和 GitHub 都正常，唯独目标站超时）。把 000 当成 404 去修，是这类排查里最容易犯的方向性错误。

到这里结论很尴尬：站点没有结构性死链，但 Google 坚持说有一个 404。唯一的办法是回 GSC 把具体 URL 找出来。

第三步：拿到 URL，案情反转

在 GSC 里点开"未找到 (404)"那一行，示例 URL 是：

查仓库：spec/ 目录下只有 ecocompute-protocol-v1.1.html 和它的 markdown 源文件，没有 index.html。GitHub Pages 不做目录列表，所以 /spec/ 从建站第一天起就是 404，而且只要不补文件就永远 404。

但真正的反转在下一层——谁把这个 URL 喂给了 Google？

顺着引用链查，源头找到了，而且就在我自己身上：协议文档的 markdown 第 12 行写着

rendered at quantenergy.tech/spec/

而且不止文档——这个地址还写进了 Zenodo 上协议的 DOI 档案记录描述里。两处都是公开可抓取的文本。

也就是说：Google 没有犯错，任何顺着学术引用来访问的人也没有犯错。是我的文档指了一个从未存在过的地址。每次有爬虫或读者按图索骥，都撞在一堵 404 的墙上——而且这堵墙我立了半年都没察觉。

根因：引用即承诺

这次排查给我的最大触动，可以浓缩成一句话：

你写进文档、论文、DOI 档案、README 里的每一个 URL，都会被当真。

写文档的时候，"内容渲染在 spec 目录下"只是一句描述；但对爬虫和读者来说，那是一个地址、一个承诺。学术场景尤其如此——Zenodo 记录是长期存档，写的 URL 会跟着 DOI 存活很多年。引用越权威、越持久，地址失效的代价越高。

还有一个时间线细节值得注意：GSC 显示这个 404 的首次检测日期，正是我大改网站的那天（新博客、新页面、Pages 多次重建）。大量新增页面触发 Google 重新抓取全站，顺带把这个一直存在的死链翻了出来——它不是新出现的，只是第一次被看见。

修复：三件事，零新增内容

修复哲学从一开始就定死了：协议内容一行不动。这不是内容变更，是让一个已被引用的地址学会应答。具体三个动作：

1. 新增 spec/index.html 目录页。 套站点统一模板，内容是"一个顺着引用来到这里的人"最需要的东西：

• 当前版本（v1.1）的渲染链接
• canonical DOI（版本 DOI + concept DOI）
• 一张"哪一层在哪"的地图：协议 / schema / 方法 / changelog 分别住在哪
• 一句话说明：Zenodo 档案，而不是任何 URL，才是权威引用对象

2. sitemap.xml 补条目。 让 Google 尽快发现并收录新页，缩短 404 记录的清除周期。

3. changelog 记档。 我们团队有条铁律：任何对外可见的变更当天记档。这次的记档里我如实写了"self-inflicted"（自己造成的）——复盘的价值就在于不粉饰。

修复上线后，/spec/ 返回 200，页面、DOI、层次地图全部渲染正确。最后一步是在 GSC 里点"验证修正情况"——Google 会重新抓取，几天后这条 404 记录自动清除。这一步很多人会忘：修了代码，但不去通知搜索引擎，记录还会在报告里躺很久。

顺手自查出的第二个 bug

修复推送时还发现一个细节，也值得写进来：检查远端 changelog 时，发现我前一天插的新条目排在了旧条目下面——违反了 changelog 的新旧排序约定。原因是我插入时只看了插入锚点，没看全局顺序。发布后多看一眼线上实际状态，这类低级失误当场就能抓住，否则它会在页面上安静地错几个星期。

带走的三条经验

1. GSC 报告先分类再动手。 备用网页（有规范标记）、尚未编入索引，这两类是正常状态，不是待修项。真正要追的只有 404、服务器错误和重定向链。
2. 000 ≠ 404。 网络层失败和 HTTP 404 是两回事，排查时先区分，否则会修一个不存在的问题。
3. 引用即承诺。 文档、论文、DOI 档案里写的 URL 迟早会被访问。定期把"所有对外材料里写过的地址"拉个清单和 sitemap 对照一遍——这次的教训是，最危险的不是你链接出去的地址，而是你声称存在的地址。

本文是 EcoCompute 项目的一次真实线上排查复盘。EcoCompute 用 NVML 实测数据回答「该不该量化你的大模型」：主数据集 DOI 10.5281/zenodo.19647290，RTX 4090 深测 DOI 10.5281/zenodo.22037483。容器化基准与复现仓库 github.com/hongping-zh/ecocompute-mlcube。