GitHub Pages 404与空白页终极排查指南

将项目部署到 GitHub Pages 后，最让人抓狂的莫过于满心欢喜地打开链接，却看到无情的 404 Not Found，或者是纯白一片的屏幕（空白页）。本文将带你深入剖析这两种常见故障，并提供详细的排查路径，帮你快速让页面恢复正常。

一、为什么会出现 404 Not Found？

404 错误意味着 GitHub 的服务器找不到你想访问的页面资源。

常见原因及解决办法：

根目录缺少入口文件 GitHub Pages 默认寻找根目录下的 index.html 或 index.md。如果你的首页命名为 main.html 或放在了子文件夹中，就会返回 404。 修复：将首页重命名为 index.html，并确保它在你所选择发布的根目录下。
分支或目录配置错误 在仓库的 Settings -> Pages 中，检查你发布的分支是否正确（例如，代码在 main，但 Pages 设置了 gh-pages 分支），以及目录是否选错（如 /root 或 /docs）。
大小写敏感问题 GitHub 服务器是大小写敏感的。如果在代码中链接了 <img src="Logo.png">，但实际文件名为 logo.png，那么该图片就会报 404。
构建尚未完成 如果你刚推送代码，Actions 可能还在排队或执行中。请到仓库的 Actions 标签页查看部署状态。

二、为什么会出现白屏（空白页）？

如果页面没有报 404，但内容是一片空白，按 F12 打开浏览器开发者工具，你通常会在 Console 中看到满屏飘红的 404 错误（指引的 JS/CSS 资源找不到）。这主要是前端框架配置不当引起的。

1. 基础路径（Public Path / Base URL）错误

这是 Vue / React / Angular 项目最常见的踩坑点。如果你部署的是“项目站点”（URL 为 xxx.github.io/repo-name/），那么资源的相对路径必须加上 /repo-name/。否则，浏览器会去 xxx.github.io/css/app.css 寻找资源，自然找不到。 修复方法：

Vue (Vite)：在 vite.config.js 中设置 base: '/repo-name/'。
React (Create React App)：在 package.json 中添加 "homepage": "https://username.github.io/repo-name"。

2. 路由模式问题（History vs Hash）

GitHub Pages 原生不支持单页应用（SPA）的 HTML5 History 路由模式。当你刷新非首页的 URL 时，由于服务器上没有对应的 HTML 文件，会导致 404 或白屏。 修复方法： 将前端路由模式改为 Hash 模式（URL带有 #），或者使用专门的 404 重定向黑科技（如 spa-github-pages 方案）。

三、故障排查逻辑链路

遇到页面问题，请冷静按照以下思路逐一排除：

1. 软件/代码层面排查

检查本地构建产物 dist 文件夹，双击 index.html，看是否在本地就已经是白屏了。
仔细核对项目配置里的 base 或 homepage 字段。

2. 账号/缓存问题排查

浏览器缓存：有时 GitHub 已经更新，但你的浏览器依然加载旧版本。使用 Ctrl + F5（Windows）或 Cmd + Shift + R（Mac）硬刷新。
CDN 延迟：GitHub Pages 依赖 CDN 分发，配置更改可能需要几分钟才能在全球节点生效。

3. 网络与代理层面排查

如果你在本地排查时，发现连 GitHub 的 Actions 日志都加载不出来，或者样式表长时间处于 Pending 状态，说明你的网络连接存在异常。

网络环境基础排查清单

✓ 确认已清除浏览器缓存和 Cookie
✓ 确认代理客户端（如 Clash/v2rayN）已正常启动并接管系统流量
✓ 确认当前节点并非处于故障或高延迟状态
✓ 尝试切换全局路由模式或更新本地分流规则
✓ 若为 PC 端，检查系统时间是否准确自动同步

完成上述基础排查后，再进行本教程针对性的深度检查。

有时，我们在排查网页白屏问题时，开启了系统的全局代理。某些劣质代理节点的 DNS 缓存非常久，或者劫持了静态资源，导致你看到的始终是错误的页面状态。

4. 节点质量影响排查与验证

作为开发者，排除故障时最怕的就是被不稳定的网络环境误导。

代理节点缓存污染：有些免费代理或低端 VPN推荐 工具，为了节省流量，会在其服务端强制缓存网页资源。这会导致你推送了修复代码，但在你的电脑上死活看不到最新效果，产生“灵异事件”。
连接超时：在查看 GitHub Actions 的详细报错日志时，如果节点速度太慢，控制台日志会不断断开连接。

推荐解决方案：在进行前端部署与线上故障排查时，务必使用一个网络质量过硬的 稳定机场。在选择 机场推荐 时，不仅要看网速，还要关注其是否支持纯净的直连策略和不随意劫持 HTTP 流量。一款好的 翻墙机场 应当能够为你提供真实、低延迟的海外访问体验，确保你看到的 GitHub 页面状态与全球其他用户完全一致，从而避免在排查 404 和白屏问题时走弯路。

四、总结

GitHub Pages 的 404 和空白页问题，90% 都是由于路径配置和大小写不敏感等细节疏忽造成的。通过开发者工具检查资源加载情况，调整打包配置中的 base URL，通常能迎刃而解。同时，保持一个干净、无缓存干扰的网络环境，将使你的排查过程事半功倍。

GitHub Pages 404与空白页终极排查指南 ​

一、 为什么会出现 404 Not Found？ ​

常见原因及解决办法： ​

二、 为什么会出现白屏（空白页）？ ​

1. 基础路径（Public Path / Base URL）错误 ​

2. 路由模式问题（History vs Hash） ​

三、 故障排查逻辑链路 ​

1. 软件/代码层面排查 ​

2. 账号/缓存问题排查 ​

3. 网络与代理层面排查 ​