GitHub Pages 出现404错误的三大主因是：仓库未公开、缺少根目录下的index.html文件、资源路径未用相对写法；此外还需注意仓库命名规范、Pages源设置准确、路径大小写敏感及单页应用需配置404.html fallback。
能，但必须满足三个硬性条件：仓库公开、首页叫 index.html、资源路径用相对写法。 其他所有“看似正常却打不开”的问题，90% 都卡在这三点上。
为什么 push 了还是 404？检查仓库命名和 Pages 源设置
GitHub Pages 不是“有文件就能访问”，它分两种托管模式，行为完全不同：
- 用户主页（
username.github.io）：仓库名必须严格等于你的用户名.github.io，且index.html必须在main分支根目录下——不能放在/src或/dist子目录里 - 项目页（任意仓库名，比如
my-landing-page）：不需要特殊命名，但必须进 Settings → Pages → Source 手动选分支（如main）和文件夹（如/(root)），保存后等 1–2 分钟 - 常见错误：
Repository name填成my-site却想走用户主页路线；或仓库名对了，但index.html实际在/public/index.html，Pages 设置又没改文件夹路径，结果一直 404
页面空白或 CSS/JS 加载失败？十有八九是路径写错了
本地双击打开 index.html 能看到样式，一推到 GitHub Pages 就白屏或控制台报 Failed to load resource: the server responded with a status of 404 ()，基本就是路径问题。
- 绝对路径（以
/开头）会从域名根开始找，比如/css/style.css在项目页https://user.github.io/repo-name/下会被解析成https://user.github.io/css/style.css—— 显然不存在 - 正确做法：全部改用相对路径，例如
./css/style.css、../images/logo.png；或者加<base href="./">到中（注意结尾斜杠） - 大小写敏感：
CSS/style.css和css/style.css是两个路径，Git 提交时大小写不一致也会导致 404
用 gh-pages 或构建工具部署？先确认你真需要它
如果你的 HTML 模板就是纯静态文件（没用 Vite、React、Vue 等框架），根本不用装 gh-pages、不用配 build 脚本、不用生成 dist 目录——直接上传 index.html 和配套资源就行。
立即学习“前端免费学习笔记（深入）”；
- 只有当你用了前端框架且输出带 hash 的构建产物（如
main.xxyz.js），才需要gh-pages或类似工具自动推送dist文件夹 - Vite 用户务必在
vite.config.js里设base: "./"，否则构建后资源路径默认带/前缀，上线必挂 - Create React App 用户需在
package.json加"homepage": "."，否则react-router的路由和资源引用全错位
最容易被忽略的一点：GitHub Pages 默认不支持服务端重定向，所以单页应用（SPA）刷新页面会 404。如果模板含前端路由，得手动放一个 404.html，内容跟 index.html 一样——GitHub Pages 会在找不到路径时 fallback 到它。
