使用Sphinx在GitHub部署文档站点遇404错误求助

分支与文件结构验证 #

• 确认gh-pages分支的根目录下是否直接包含Sphinx生成的所有HTML静态文件（包括index.html、_static、_templates等文件夹），不要嵌套在_build/html这类子目录里——GitHub Pages只会读取部署分支指定位置的根文件，嵌套会导致路径匹配失败。
• 检查分支提交记录，确认本地生成的静态文件确实完整推送到了远程gh-pages分支，没有遗漏或.gitignore误屏蔽文件。

GitHub Pages配置核对 #

• 进入仓库的「Settings」→「Pages」页面，确认部署来源选择的是gh-pages分支，且「文件夹」选项设置为/(root)，而非其他子路径。
• 检查仓库是否为公开仓库：私有仓库在未升级GitHub Pro的情况下，GitHub Pages无法正常访问（会返回404）。

静态资源路径检查 #

• 打开本地生成的index.html，查看页面内引用的CSS、JS等资源路径是否为相对路径（比如_static/css/theme.css），而非绝对路径（比如/docs/_static/...）。如果是绝对路径，需要修改Sphinx配置文件conf.py中的html_baseurl或html_static_path，确保路径适配GitHub Pages的域名结构。
• 若仓库是组织下的项目，或使用自定义域名，需确认conf.py中html_baseurl设置为正确的Pages访问地址（比如https://<用户名>.github.io/<仓库名>/），避免资源路径解析错误。

缓存与访问路径验证 #

• 访问时直接输入完整的Pages地址（比如https://<用户名>.github.io/<仓库名>/index.html），而非只输域名，排除默认首页未被正确识别的问题。
• 强制刷新浏览器缓存（Ctrl+F5），避免旧的404页面被缓存导致误判。
• 检查GitHub Pages的部署状态：在仓库的「Actions」→「Pages build and deployment」中查看最新部署记录的日志，确认是否有隐性的文件权限或路径错误（即使主流程提示成功，日志细节里可能有线索）。

自定义域名相关排查（如果使用） #

• 若配置了自定义域名，检查仓库根目录的CNAME文件是否存在且内容正确，同时确认域名的DNS解析记录（A/AAAA或CNAME）已正确指向GitHub Pages服务器，且GitHub已验证域名所有权。

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