GitHub Pages返回404主因是index.html位置错误、Pages源设置未生效或资源路径非相对写法；须确保index.html严格命名且位于所选源根目录、仓库名符合username.github.io规范（用户页）、所有路径用./或，单页应用还需根目录放404.html fallback。
GitHub Pages 返回 404，基本不是代码写错了，而是它根本没找到你的 index.html——文件位置、仓库设置、路径写法三者只要错一个，就必然 404。
确认 index.html 是否在正确位置且命名准确
GitHub Pages 只认一个入口文件：index.html，且必须满足三个硬条件：
- 文件名严格为
index.html（大小写敏感，Index.html或index.HTML都无效） - 必须位于你所选「Pages 源」的根目录下（比如你设了
main分支 +/(root)，那它就得在仓库最顶层，不能在/src/index.html或/dist/index.html） - 如果是用户主页（
username.github.io），仓库名必须严格等于username.github.io，且index.html在main分支根目录
常见坑：本地用 VS Code 看着是 index.html，但 Windows 隐藏了扩展名，实际可能是 index.html.txt；Git 提交时也看不到这个隐藏后缀，导致服务器找不到文件。
检查 GitHub Pages 的源设置是否生效
Push 完代码不等于自动上线，必须手动确认 Pages 设置已保存并触发构建：
立即学习“前端免费学习笔记（深入）”；
|Git删除了文件，但还会在Git 仓库历史中遗留。 - 想要从 Git 历史移除敏感信息（密码、密钥、token、私钥） - 想要删除意外提交的大文件 - 想要重写 Git 历史、移除特定文件的所有痕迹 - 提到 "force push"、"重写 commit 历史" - 需要从所有分支、所有 tag 中删除某个文件
- 进仓库 Settings → Pages → Source，确认分支（如
main）和文件夹（如/(root)）选对了 - 改完点 Save，等 1–2 分钟——状态栏会从 “Building” 变成 “Deployed”，URL 才真正可用
- 如果之前用过
/docs分支或/gh-pages分支，现在切回main，旧设置可能残留，务必重新 Save 一次
注意：Settings 页面里没有 “Deployed” 状态，或者 URL 显示 “Your site is ready to be published at …” 但打不开，大概率是还没构建完，别急着排查其他地方。
验证资源路径是否全用相对写法
本地双击打开能看样式，一推到 GitHub Pages 就白屏或控制台报 Failed to load resource: the server responded with a status of 404 ()，90% 是路径问题：
- 绝对路径（以
/开头）会从域名根开始找：/css/style.css在项目页https://user.github.io/repo-name/下，会被请求成https://user.github.io/css/style.css（显然不存在） - 正确做法：全部改用相对路径，如
./css/style.css、../js/app.js；或在加<base href="./">（结尾斜杠不能少） - 大小写也要一致：
CSS/style.css≠css/style.css，Git 提交时改名不重命名，也会导致 404
单页应用（SPA）必须配 404.html fallback
如果你用 Vite、Vue Router 或 React Router 并开启了 history 模式，访问 /about 刷新就 404，是因为 GitHub Pages 没有服务端路由能力：
- 必须在仓库根目录放一个
404.html文件（不能是404.md，除非加 YAML front matter） - 这个文件内容要能捕获 URL 并重写回
index.html，例如 spa-github-pages 方案里的 JS 逻辑：l.replace(...) - 关键配置
pathSegmentsToKeep：项目页（user.github.io/repo-name）需设为1，否则深层路由无法保留仓库名前缀
最容易被忽略的是：这个 404.html 必须是纯 HTML 文件，不能依赖构建工具生成；且它本身不能有外部 JS/CSS 引用失败，否则 fallback 逻辑就断了。
