使用Gatsby搭建的GitHub Pages无法加载根目录index.html求助

我之前也碰到过同款诡异问题——明明index.html就在那，根路径死活打不开，加个/index或/index.html却能正常加载。给你几个实用的排查方向和解决方案：

1. 核对GitHub Pages的核心部署设置 #

先直奔仓库的「Settings -> Pages」页面检查两个关键项：

• 是不是确实选了master分支作为部署源？别不小心选回dev或者其他分支了
• 部署目录是不是设为「/(root)」？要是误选了「/docs」，GitHub Pages会默认去docs目录找首页，直接导致根路径失效，但直接访问index.html能绕过这个规则

2. 检查Gatsby的路径配置 #

打开项目根目录的gatsby-config.js，重点看pathPrefix配置：

• 因为你的站点是部署在根域名（zana-a.github.io），pathPrefix应该留空或者设为"/"，绝对不能加任何额外路径（比如"/site"这类）
• 如果之前误设了前缀，Gatsby会给所有资源路径自动加上这个前缀，导致根路径的路由匹配失败，但直接访问index.html能加载静态内容

修改后记得重新清理+构建：

gatsby clean
gatsby build

3. 强制刷新缓存（本地+GitHub端） #

GitHub Pages偶尔会有缓存延迟，尤其是刚部署完的时段：

• 本地访问根路径时按Ctrl+Shift+R（Windows/Linux）或Cmd+Shift+R（Mac）强制刷新浏览器缓存，避免本地旧缓存干扰
• 在「Settings -> Pages」页面，随便改个小设置（比如把分支临时换成其他再改回master），触发一次重新部署，让GitHub Pages彻底刷新缓存

4. 确认master分支的文件结构 #

去GitHub仓库直接查看master分支的文件列表，确保index.html是直接放在根目录下，而不是嵌套在public或其他子文件夹里。
如果是用脚本自动构建部署的，要确保脚本是把public文件夹内的所有文件复制到master分支的根目录，而不是把整个public文件夹上传上去。

5. 排查Gatsby构建产物的有效性 #

本地打开public/index.html看看内容是否正常，有没有正确引入CSS和JS资源。如果本地打开完全正常，那基本可以排除构建产物的问题，把注意力放回部署和GitHub Pages设置上。

要是以上方法都试过还是不行，可以尝试把master分支完全清空，重新推送构建产物——有时候分支历史的遗留问题也会导致这种莫名其妙的异常。

内容的提问来源于stack exchange，提问作者user6822060