GitHub Pages 托管需满足四条件：仓库公开、首页为小写index.html、资源用相对路径（非根路径）、发布源选对分支；本地file://协议宽容，而GitHub Pages的https://严格解析路径，大小写错误或绝对路径均导致404。
能直接托管，但必须满足四个硬性条件：仓库公开、首页叫 index.html、路径用相对引用、部署源选对分支。
为什么本地双击能打开，上传 GitHub Pages 后样式/图片全丢？
根本原因是协议和路径解析方式变了：本地双击走的是 file:// 协议，浏览器对相对路径宽容；GitHub Pages 走的是 https://，所有资源必须从网站根目录开始严格解析。
- 检查所有
<link>、<script>、<img>标签的href或src—— 不能以/开头（比如/css/style.css），否则会去域名根找，而不是当前仓库根 - 正确写法是纯相对路径：
css/style.css、images/logo.png、../js/main.js - 用浏览器开发者工具的
Network面板看 404 请求，直接定位哪个路径错了
GitHub Pages 设置时该选 main 还是 gh-pages 分支？
绝大多数情况选 main（或 master）分支根目录即可，除非你明确需要隔离源码和构建产物。
- 个人主页仓库（
username.github.io）只支持main或master分支的根目录或/docs文件夹 - 普通项目页仓库（比如
my-blog）默认也只支持main分支根目录；若要用gh-pages分支，需手动在 Settings → Pages → Build and deployment 中切换 Source - 选错分支会导致页面一直显示 “Your site is published at …” 但点开是 404
上传后访问链接是 404，但文件明明存在？
不是文件没传上去，而是 GitHub Pages 的命名和大小写规则极其严格。
立即学习“前端免费学习笔记（深入）”；
-
index.html必须全部小写，Index.html、INDEX.HTM、home.html全部无效 - 仓库必须是公开的（Private 仓库默认关闭 Pages，Pro 用户才可开启）
- 首次启用 Pages 后，可能要等 1–2 分钟才生成 URL，刷新太快会看到 “Page build failure” 提示（实际只是延迟）
- URL 格式固定：
https://<username>.github.io（个人主页）或https://<username>.github.io/<repo-name>（项目页）
最容易被忽略的是：GitHub Pages 不运行任何服务端逻辑，也不重写 URL。如果你写了 <a href="/contact"> 却没有真实存在的 contact.html 文件，点击就会 404 —— 它不会像 Vercel 那样自动 fallback 到 index.html。
