在把静态项目推送到 GitHub Pages 后，最让人困惑的情况之一就是访问地址返回 404。实际上，GitHub Pages 对入口文件有一套明确的命名规范，理解它就能解决绝大部分打不开页面的问题。
GitHub Pages 如何确定首页
GitHub Pages 在构建站点时，会依据所选分支（如 main 或 gh-pages）根目录下的固定文件名来提供首页内容。这个文件名只能是 index.html，区分大小写。也就是说，下面这些都不会被当作根首页：
- Index.html
- INDEX.HTML
- home.html
- main.html
常见导致 404 的写法
1. 文件名大小写不一致
在 macOS 或 Windows 上新建文件时，系统不严格区分大小写，本地预览正常，但推到 GitHub 后 Linux 环境区分大小写，写成 Index.html 就会 404。
2. 文件未放在分支根目录
如果你把 index.html 放在了 src/ 或 public/ 子目录，而没有在仓库设置里指定发布目录，直接访问用户名.github.io/仓库名 就会找不到。
3. 项目类型配置错误
使用 Jekyll 时若未正确输出 index.html，或 .nojekyll 文件缺失导致下划线文件被忽略，也可能引发资源 404。
快速自查清单
| 检查项 | 正确示例 |
|---|---|
| 文件名 | index.html（全小写） |
| 位置 | 发布分支根目录或指定目录 |
| 分支设置 | Settings 中 Pages 分支正确 |
用本地命令验证
可以在本地用简单脚本确认根目录是否存在标准入口文件：
#!/bin/bash # 检查当前目录是否有 index.html if [ -f "index.html" ]; then echo "入口文件存在，命名正确" else echo "未找到 index.html，请创建或重命名" fi
最小复现示例
下面是一个符合规范的 index.html 内容，可直接放在仓库根目录：
<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <title>GitHub Pages 测试</title> </head> <body> <h1>部署成功</h1> <p>这是根目录下的 index.html 文件。</p> </body> </html>
小结
遇到 GitHub Pages 404 时，先确认仓库发布分支的根目录里有没有准确命名为 index.html 的文件。这个简单的规范能避免大量无效排查。理清命名和路径规则后，静态站点部署会变得非常顺畅。
GitHub_Pages404错误index_html修改时间：2026-07-31 05:45:18