GitHub Pages部署个人主页必须严格满足三要素：仓库名须为username.github.io、内容置于main/master分支根目录、HTML资源路径用相对路径或<base href="./">；项目页需手动设置Pages源分支与文件夹；SPA刷新404需根目录放置同内容的404.html。
GitHub Pages 不是“推上去就自动能访问”的静态托管，它对仓库结构、路径写法、分支设置有硬性要求；不按规则来，90% 的 404 都是这三处出问题。
仓库名和分支必须严格匹配用户主页规则
你要部署的是个人主页（比如 https://yourname.github.io），仓库名必须是 yourname.github.io，一个字母都不能错，大小写敏感。内容必须放在 main（或 master）分支的根目录下——index.html 不能在 /src、/dist 或 /public 子目录里。
常见错误现象：
- 仓库叫
my-portfolio却想用yourname.github.io访问 → 不行，地址会变成yourname.github.io/my-portfolio - 仓库名正确，但
index.html在/docs/index.html→ 页面空白，控制台报 404 - 用了
gh-pages分支但没在 Settings → Pages 里手动选中它 → GitHub 默认只看main根目录
HTML 里的资源路径必须用相对路径或 <base>
本地双击打开 index.html 能看到图片和样式，一推到 GitHub Pages 就全挂了？大概率是写了 /css/style.css 这种以 / 开头的绝对路径。浏览器会把它解析成 https://yourname.github.io/css/style.css，而不是你仓库里的位置。
立即学习“前端免费学习笔记（深入）”；
正确做法：
- 全部改用相对路径：
./css/style.css、../images/logo.png - 或者在
<head>里加一行：<base href="./">（注意结尾斜杠） - 构建工具如 Vite 必须配
base: "./"；Create React App 必须设homepage: "."，否则生成的js和css引用仍带/
项目页（非 username.github.io）要手动指定源分支和文件夹
如果你只是想部署一个项目文档页，比如 https://yourname.github.io/myapp，那仓库名可以任意（如 myapp），但必须进 Settings → Pages → Source 手动选择：
- 分支：比如
main（不是默认自动识别） - 文件夹：比如
/(root)（根目录）或/docs（如果文件放在这里）
不点保存，就不会生效；点了之后等 1–2 分钟，再刷新页面。别信“已启用”提示就以为好了——得真能打开链接才算。
单页应用（SPA）刷新 404 必须靠 404.html
React/Vue 路由用 history.pushState 的项目，访问 /about 后刷新，GitHub Pages 会直接 404，因为它没有服务端路由回退逻辑。
解决办法只有一个：在仓库根目录放一个 404.html，内容和 index.html 完全一样。GitHub Pages 遇到任何未命中路径，都会返回这个文件，前端路由就能接管了。
注意：404.html 必须和 index.html 同级，且不能放在 /docs 里（除非你选的源是 /docs）；它不会影响正常 404 状态码，只是内容兜底。
最容易被忽略的是构建产物路径配置和 404.html 的存在性——很多人卡在刷新白屏或资源加载失败，查半天网络请求，其实就差这一行 <base href="./"> 或一个同名的 404.html 文件。
