GitHub Pages 部署 HTML 显示404错误

Question

在使用 GitHub Pages 部署静态网站时，常遇到 HTML 页面访问返回 404 错误的问题。典型场景是：项目已正确推送到 GitHub 仓库，并在 Settings 中启用了 GitHub Pages，但访问页面时仍提示“404 File not found”。该问题通常源于分支配置错误（如未指定正确的源分支，如 `main` 或 `gh-pages`）、文件路径不正确（如缺失 `index.html` 或文件位于子目录但未调整站点根路径），或 `.nojekyll` 文件缺失导致 Jekyll 构建失败。此外，自定义域名配置不当也可能触发 404。排查时应检查部署分支、提交内容结构及 GitHub Pages 构建日志，确认资源是否成功发布。

Answer 1

GitHub Pages 部署中 HTML 页面返回 404 错误的深度排查与解决方案

1. 问题背景与典型场景分析

在使用 GitHub Pages 部署静态网站时，尽管项目已成功推送到远程仓库，并在仓库的 Settings → Pages 中启用了服务，但仍频繁出现访问页面返回“404 File not found”的错误。该现象不仅影响开发效率，也对线上展示造成困扰。

常见触发场景包括：

• 部署分支配置错误（如选择了不存在或未推送内容的分支）
• index.html 文件缺失或路径不正确
• 构建产物位于子目录（如 docs/ 或 dist/），但未设置正确的源路径
• Jekyll 自动构建失败，因缺少 .nojekyll 文件导致静态资源无法正确解析
• 自定义域名配置错误，如 CNAME 记录未生效或 HTTPS 强制跳转异常

2. 排查流程：由浅入深的诊断路径

为系统性解决此问题，建议按照以下顺序进行排查：

1. 确认 GitHub Pages 是否已启用并显示“Your site is published”状态
2. 检查部署源分支是否正确（main、gh-pages 等）及对应目录设置
3. 验证仓库根目录或指定源目录中是否存在有效的 index.html
4. 查看最近一次提交是否包含必要的静态资源文件
5. 查阅 GitHub Actions 或 Pages 构建日志（若有 CI 流程）
6. 确认是否存在 .nojekyll 文件以禁用 Jekyll 处理
7. 检查自定义域名配置与 DNS 解析状态
8. 测试默认 GitHub 域名（如 username.github.io/repo）是否可访问
9. 使用浏览器开发者工具查看网络请求中的实际响应码和路径
10. 排查重定向规则或 _redirects 文件配置冲突

3. 关键配置项与解决方案对照表

问题类型	可能原因	解决方案
分支配置错误	Pages 源分支未设为 main 或 gh-pages	进入 Settings → Pages → Change source，选择正确分支
文件路径问题	index.html 不在源目录下	将 HTML 文件移至根目录或设置源为 docs/ 等子目录
Jekyll 构建干扰	无 .nojekyll 文件，Jekyll 忽略非标准结构	在站点根目录添加空的 .nojekyll 文件
自定义域名失效	DNS A 记录或 CNAME 配置错误	检查域名服务商记录指向正确的 GitHub IP 或子域
缓存问题	CDN 或浏览器缓存旧 404 响应	清除缓存或等待 TTL 过期后重试

4. 技术细节深入：Jekyll 与静态资源处理机制

GitHub Pages 默认使用 Jekyll 构建站点，其会对特定命名模式的文件夹（如 _posts, _layouts）进行处理，并忽略不符合规则的静态资源。若你的项目是纯前端应用（如 Vue、React 构建产物），必须通过添加 .nojekyll 文件来关闭自动构建流程。

# 在项目根目录创建 .nojekyll 文件
touch .nojekyll
git add .nojekyll
git commit -m "Add .nojekyll to disable Jekyll processing"
git push origin main

此举确保所有静态文件被原样发布，避免因元数据解析失败而导致资源不可见。

5. 自定义域名与 HTTPS 配置注意事项

当使用自定义域名时，需在仓库根目录或 docs/ 目录下放置 CNAME 文件，内容为完整域名（如 www.example.com）。同时，确保：

• DNS 提供商配置了正确的 A 记录（指向 GitHub Pages IP 地址）或 CNAME 记录
• 在 GitHub Settings 中勾选 “Enforce HTTPS” 前，确认证书已就绪（通常需几分钟到几小时）
• 避免在多个位置重复定义 CNAME（如同时在 DNS 和 Cloudflare 页面规则中设置）

6. 构建与部署流程可视化

以下 Mermaid 流程图展示了从本地提交到 GitHub Pages 成功发布的完整链路：

graph TD
            A[本地编写 HTML/CSS/JS] --> B[提交至 Git 仓库]
            B --> C{推送至远程分支}
            C --> D[检查 Pages 源分支设置]
            D --> E{是否存在 index.html?}
            E -->|是| F[检查 .nojekyll 文件]
            E -->|否| G[生成或移动 index.html]
            F --> H{启用自定义域名?}
            H -->|是| I[配置 CNAME + DNS]
            H -->|否| J[使用默认 github.io URL]
            I --> K[等待 DNS 生效]
            J --> L[访问页面验证]
            K --> L
            L --> M{是否返回 404?}
            M -->|是| N[查看构建日志 & 网络请求]
            M -->|否| O[部署成功]

7. 高级调试技巧：利用 API 与日志分析

对于复杂部署环境，可通过 GitHub API 查询 Pages 状态：

curl -H "Authorization: token YOUR_TOKEN" \
     https://api.github.com/repos/username/repo/pages

响应中会包含 status、url、build_duration 等关键信息。此外，在 Actions 工作流中添加日志输出，有助于定位构建阶段的文件拷贝问题。