GitHub Pages用户主页必须使用username.github.io命名仓库，且index.html需置于main分支根目录，Settings中须手动启用Pages并选择正确分支和根路径，否则将导致404。
GitHub Pages 不需要你写任何构建脚本就能上线静态网站，但前提是仓库结构、分支和配置必须对得上——错一个环节，index.html 就不会被识别为首页，或者页面压根 404。
仓库命名必须是 username.github.io
这是用户主页（即直接访问 https://username.github.io）的硬性要求。GitHub 会自动把该仓库的 main（或 master）分支根目录当作网站根路径。
- 如果仓库叫
my-portfolio，哪怕内容完全一样，GitHub Pages 也不会把它当个人主页用，只能作为项目页（路径变成https://username.github.io/my-portfolio） - 用户名含大写字母或特殊符号？不行，GitHub 用户名全小写，且只支持字母、数字、短横线
- 已存在同名仓库？先删掉旧的，再新建——GitHub 不允许重复命名
git push 后页面仍 404 的常见原因
推送成功 ≠ 页面可访问。GitHub Pages 构建有延迟，且依赖明确的发布源设置。
- 没进 Settings → Pages 手动启用：默认不开启，必须点开并选择分支（如
main）和文件夹（/ (root)），点 Save - 推送的是
dev分支，但 Settings 里选了main：分支不匹配，页面不会更新 -
index.html不在仓库根目录：比如放在src/或public/下，GitHub Pages 默认不递归查找，必须挪到最外层 - 文件权限异常（极少见）：本地用
git add -f index.html强制添加，避免被 .gitignore 忽略
自定义域名后 HTTPS 失败或跳转回 username.github.io
绑定自定义域名后出现跳转或证书警告，基本是 DNS 和 GitHub 两侧没对齐。
- CNAME 文件必须放在仓库根目录，内容只有一行：你的域名（如
www.example.com），不能带http://或末尾斜杠 - 域名服务商处要配两条记录：CNAME 指向
username.github.io（仅用于 www 子域），或 A 记录指向 GitHub 的四个 IP（185.199.108.153、185.199.109.153、185.199.110.153、185.199.111.153）——裸域（@）必须用 A 记录 - GitHub Pages 设置里填了
example.com却没勾选 “Enforce HTTPS”：建议勾选，但首次勾选可能需等几分钟证书生成，期间页面会短暂不可用
最容易被忽略的是：每次改完 CNAME 或 DNS，GitHub 需要重新验证域名所有权，这个过程不是实时的——有时候等 10 分钟才生效，别一刷新 404 就重推代码。
