github pages 不再强制使用 gh-pages 分支，推荐直接用 main 分支根目录或 /docs 目录部署；禁用 jekyll 可加 .nojekyll 文件；自定义域名需 cname 文件、settings 配置及 dns 解析三者配合。
GitHub Pages 的 gh-pages 分支早就不是必须的了
GitHub Pages 现在默认支持从 main（或 master）分支的 / 或 /docs 目录发布，gh-pages 分支只是历史遗留选项。除非你用的是 Jekyll 且需要自定义构建流程，否则别再无脑新建 gh-pages 分支——它只会增加推送、同步和权限管理的麻烦。
实操建议：
- 新建仓库后，直接往
main分支提交 HTML/CSS/JS 文件，然后在 Settings → Pages → Source 里选Deploy from a branch→main→/ (root) - 如果想把文档和代码分开，把静态文件放
docs/index.html，Source 选/docs目录即可 - 确认 GitHub Pages 已启用：保存设置后，页面会显示类似
https://<username>.github.io/<repo></repo></username>的地址，几秒到两分钟内生效
git subtree push 不适合日常更新 Pages 网站
很多人搜到用 git subtree push 把 build/ 目录推到 gh-pages 分支，这在 CI 尚未普及的年代有用，但现在反而容易出错：它会重写历史、污染 gh-pages 分支的 commit 记录，且本地误操作可能覆盖线上内容。
更稳妥的做法是：
- 用 GitHub Actions 自动构建并部署：比如
actions/jekyll-build-pages（Jekyll），或通用型peaceiris/actions-gh-pages（支持任何静态生成器） - 手动部署时，直接
git add . && git commit -m "deploy"到主分支对应目录，而不是折腾 subtree - 若坚持用命令行部署，优先考虑
ghCLI：gh pages deploy --dir ./dist（需先安装gh并登录）
自定义域名 + HTTPS 强制开启必须改 CNAME 和设置项
加 CNAME 文件只是第一步，漏掉 Settings 里的配置，HTTPS 会一直灰色不可用，访问时仍走 http:// 或报证书错误。
关键步骤缺一不可：
- 仓库根目录放纯文本
CNAME文件，内容只有一行：你的域名（如example.com），**不带http://，不带路径，末尾无空行** - Settings → Pages → Custom domain 输入相同域名，并勾选
Enforce HTTPS - DNS 解析需指向 GitHub：A 记录到
185.199.108.153等四个 IP，或用 ALIAS/ANAME（部分 DNS 提供商支持），CNAME 只适用于子域名（如www.example.com）
Jekyll 构建失败常见于 _config.yml 编码或插件问题
GitHub Pages 默认用 Jekyll 构建，但只允许白名单插件，且要求 _config.yml 是 UTF-8 编码（BOM 会导致解析失败，错误信息为 YAML Exception: invalid byte sequence in UTF-8）。
排查要点：
- 用编辑器检查
_config.yml是否含 BOM：VS Code 底部状态栏看编码，Sublime Text 用 File → Reopen with Encoding → UTF-8 - 禁用所有第三方插件，只保留
plugins: []或删掉该字段，再测试能否构建成功 - 不想被 Jekyll 干预？在仓库根目录加一个空的
.nojekyll文件，GitHub 就会跳过构建，直接托管你提交的文件
真正卡住人的往往不是“怎么部署”，而是 DNS 生效延迟、CNAME 文件多了一个空格、或者本地预览用的是 Jekyll 4.x 而 GitHub 还在跑 3.9 —— 部署前先看 Settings → Pages 页面右上角的构建日志，比反复推代码有用得多。
