GitHub Actions部署文档至GitHub Pages遇404及显示异常问题

1. 确认gh-pages分支的文件结构 #

登录GitHub仓库，切换到gh-pages分支，检查根目录下是否存在index.html文件：

• 如果index.html不在根目录，说明peaceiris/actions-gh-pages的publish_dir配置有误，或者构建产物路径不对。
• 先在本地执行make html，确认docs/build/html下的文件是否完整，尤其是index.html是否存在且内容正常。

2. 调整GitHub Actions工作流配置 #

修改工作流中的peaceiris/actions-gh-pages步骤，添加force_orphan: true参数，强制生成干净的gh-pages分支：

- name: Deploy to GitHub Pages
  uses: peaceiris/actions-gh-pages@v3
  if: github.ref == 'refs/heads/main'
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: docs/build/html
    force_orphan: true  # 新增：创建独立的gh-pages分支，彻底清除旧内容

这个参数会确保gh-pages分支只包含你部署的文档内容，避免和旧分支内容混合导致结构混乱。

3. 检查GitHub Pages的部署设置 #

进入仓库的Settings -> Pages页面：

• 确认Source选择的是GitHub Actions（而非Deploy from a branch）。
• 查看页面顶部的部署状态，若显示“Your site is live at xxx”再尝试访问；若显示部署中，等待5-10分钟再操作。

4. 处理CDN缓存问题 #

GitHub Pages依赖CDN分发内容，即使部署成功，缓存可能未更新：

• 用浏览器强制刷新页面（Windows/Linux按Ctrl+F5，Mac按Cmd+Shift+R）。
• 清除浏览器缓存后重新访问目标URL。

5. 确认访问URL的正确性 #

确保访问的URL符合GitHub Pages规则：

• 用户仓库：https://<你的GitHub用户名>.github.io/<仓库名>/
• 组织仓库：https://<组织名>.github.io/<仓库名>/
  如果URL遗漏仓库名或拼写错误，会直接导致404或显示仓库根目录的README。

6. 排查Sphinx构建问题 #

在本地执行以下命令，确认构建流程是否正常：

cd docs
make clean  # 清除旧构建产物，避免缓存干扰
make html

检查docs/build/html目录下的index.html是否能正常打开、内容是否完整。如果本地构建就有问题，需要排查Sphinx配置（比如conf.py中的路径设置）或依赖安装是否完整。

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