GitHub Pages 404：用三个对照测试定位问题

遇到GitHub Pages 404，先区分站点根路径、项目路径和自定义域名。本文提供可操作的对照记录表思路，帮助你缩小故障范围并验证修复结果。

GitHub Pages 出现404时，反复重新提交代码容易掩盖真正原因。更有效的办法是固定一次部署，分别访问三个地址，再根据差异选择检查方向。下面是一套原创排查顺序，不要求你先懂全部部署术语。

第一步：记录三个访问结果

打开仓库的Pages设置，记下页面给出的站点地址。对项目仓库，应特别留意地址是否包含仓库名路径。接着记录站点入口、某篇文章地址、自定义域名入口的状态。每次只改一个设置，记录修改前后时间和对应提交编号。

如果站点入口也404，优先检查发布任务和发布目录。如果入口正常、文章404，优先检查文件路径、大小写和静态导出结构。如果默认地址正常、只有自定义域名异常，再转向域名设置。这种分支比一次修改DNS、构建脚本和主题配置更容易验证。

第二步：把发布目录和实际产物对齐

确认本次部署确实完成，而非仅仅代码提交成功。打开部署对应的构建日志，找出实际输出目录，再核对入口文件位于哪一层。不要只看本地项目里有index.html；它必须进入本次发布产物。

给自己写下一个路径映射，例如：文章源文件的位置、构建后的HTML位置、浏览器实际请求路径。这三者不一定相同。项目站点的资源前缀也应跟随站点路径，避免首页存在但样式和图片请求404。

第三步：做最小修复验证

先修复一个入口或一篇文章，再用浏览器无痕窗口访问。查看开发者工具的网络面板，区分文档请求404和图片、脚本请求404。页面没有样式并不等于页面文档没有发布。

修复记录建议包含：错误地址、部署编号、唯一修改项、返回状态、页面是否完整、验证时间。如果只在自己电脑恢复，而另一台设备仍有问题，保留这条差异，不要急着宣布全面解决。最后复查旧链接是否仍能到达对应文章，避免修复首页后留下批量失效地址。

参考资料与适用范围

GitHub：Pages 404排查

Cloudflare：静态部署调试参考

本文为原创方法教程，不包含未经运行的性能测试结论。示例地址和命令需要替换为你自己的环境；官方服务与界面可能更新，操作前应复核当前文档。资料核对日期：2026年10月7日。