Doxygen文档部署GitHub Pages成功后出现404错误求助

1. 检查Actions发布步骤的文件路径 #

• 确认Doxygen生成的静态文件目录（通常是html/）是否被正确指定为上传工件的路径。用actions/upload-pages-artifact时，path必须精确指向生成的HTML根目录，不能只写父目录。示例配置：

  - name: Upload Pages artifact
    uses: actions/upload-pages-artifact@v3
    with:
      path: ./html  # 必须指向Doxygen生成的html文件夹
  

• 查看构建日志里「Upload artifact」步骤的输出，确认上传的文件数量和结构，重点看是否有index.html在根目录。

2. 验证Pages部署源配置 #

• 进仓库「Settings」→「Pages」，确认「Build and deployment」下的「Source」选的是「GitHub Actions」，别选成了特定分支。
• 去「Actions」→「Deployments」页面，看最新部署记录状态是不是「active」，且工件内容正确。如果部署显示成功但内容空，大概率是上传工件时路径错了。

3. 核对Doxygen配置的输出路径 #

• 打开Doxyfile，检查OUTPUT_DIRECTORY是不是设置成了正确的输出目录（比如./html），或者构建时有没有通过命令行参数指定正确路径。
• 可以在构建步骤后加个验证命令，确保生成了index.html：

  - name: Check generated files
    run: |
      ls -la ./html
      test -f ./html/index.html || echo "Error: index.html missing!"
  

4. 匹配Pages部署的根目录 #

• 项目仓库的Pages访问路径是https://<用户名>.github.io/<仓库名>/，所以Doxygen生成的页面相对链接要适配这个子路径。可以在Doxyfile里设置HTML_BASEHREF为/<仓库名>/（比如你的仓库就设为/tinyurdf/），这样所有相对链接都会自动指向正确路径。

5. 排除缓存或延迟问题 #

• GitHub Pages部署后可能有CDN缓存，先强制刷新页面（Ctrl+F5），或者等5-10分钟再访问。
• 用浏览器开发者工具的「Network」标签，看index.html的返回状态码，如果是404，检查请求的URL路径有没有遗漏仓库名后缀。

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