GitHub Pages 部署完全指南：从入门到精通，避开常见陷阱
使用 GitHub Pages 搭建个人博客、项目文档或静态网站，是许多开发者的首选方案。其流程看似简单，但在实际操作中，新手常常会陷入几个典型的误区，导致部署失败或效率低下。本文将为你详细拆解 GitHub Pages 部署的核心步骤与关键细节，帮助你高效、稳定地完成网站发布。
关于部署分支：gh-pages 分支已非必选项
首先需要纠正一个广泛存在的认知误区：部署 GitHub Pages 网站并不强制要求使用 gh-pages 分支。这个分支更多是早期 Jekyll 工作流的遗留产物。如今，GitHub Pages 官方推荐并支持直接从 main（或 master）分支的根目录，或专门的 /docs 文件夹进行部署。刻意创建 gh-pages 分支反而会增加分支管理和同步的复杂度。
那么，当前推荐的部署方式有哪些？
- 最简方案（根目录部署）：将你的网站源码（如 index.html, style.css, script.js）直接提交到仓库的
main分支根目录。随后，进入仓库的 Settings → Pages → Build and deployment，在 Source 部分选择 “Deploy from a branch”，分支选择main，文件夹选择/(root)。 - 代码与文档分离（/docs 目录部署）：如果你希望将网站文件与项目源代码分开管理，可以在仓库中创建一个
docs文件夹，将所有静态网站文件放入其中（例如docs/index.html）。在 Pages 设置中，源分支选择main，文件夹则选择/docs。 - 访问与生效：保存设置后，GitHub 会提供一个格式为
https://<用户名>.github.io/<仓库名>的访问地址。通常在一两分钟内，你的网站即可通过该链接访问。
部署工具选择：为何应避免使用 git subtree push
在网络上的老旧教程中，常会看到使用 git subtree push 命令将构建目录（如 dist/ 或 build/）推送到 gh-pages 分支的方法。这种方法在现代工作流中已被视为“反模式”，因为它会强制重写远程分支的提交历史，容易造成历史记录混乱，且在多人协作或误操作时可能导致线上内容被意外覆盖。
更现代、更可靠的部署策略推荐：
- 自动化部署（首选）：利用 GitHub Actions 实现自动化构建与部署。例如，对于 Jekyll 项目，可使用官方 Action
actions/jekyll-build-pages；对于 VuePress、Hugo、VitePress 等静态站点生成器，社区广泛使用的peaceiris/actions-gh-pages是一个通用且强大的选择。 - 手动部署（简单直接）：对于纯静态文件，最直接的方式就是按照上述分支设置，将文件提交到指定目录（根目录或
/docs），然后执行git push。这比任何复杂的 subtree 操作都更清晰、更安全。 - 官方 CLI 工具：GitHub 官方命令行工具
gh也提供了便捷的部署命令。安装并认证后，可以使用gh pages deploy --dir ./dist来部署指定目录。
自定义域名配置：完整步骤确保 HTTPS 强制启用
为 GitHub Pages 绑定自定义域名是常见需求，但许多用户在配置后会发现 HTTPS 无法强制开启，或网站访问异常。这通常是因为配置步骤不完整。要成功绑定域名并启用 HTTPS，必须完成以下三个环节：
- 第一步：创建 CNAME 文件：在仓库的根目录或你选择的部署目录（如
/docs）下，创建一个名为CNAME的纯文本文件。文件内容仅有一行，即你的域名（例如example.com或www.example.com）。关键提示：不要包含协议头（http/https），不要添加路径，文件末尾确保没有多余的空行或空格。 - 第二步：在 GitHub 设置中配置：进入仓库的 Settings → Pages → Custom domain，输入与 CNAME 文件中完全一致的域名，并点击 Save。稍等片刻，待域名验证通过后，务必勾选下方出现的
Enforce HTTPS复选框，以启用强制 HTTPS 访问。 - 第三步：配置 DNS 解析：前往你的域名注册商或 DNS 服务商控制面板，添加 DNS 记录。
- 若绑定的是根域名（如 example.com）：通常需要添加 4 条 A 记录，分别指向 GitHub Pages 的 IP：
185.199.108.153,185.199.109.153,185.199.110.153,185.199.111.153。 - 若绑定的是子域名（如 www.example.com）：添加一条 CNAME 记录，将主机记录指向
<你的用户名>.github.io。
- 若绑定的是根域名（如 example.com）：通常需要添加 4 条 A 记录，分别指向 GitHub Pages 的 IP：
Jekyll 构建失败排查：编码与插件是关键
GitHub Pages 默认使用 Jekyll 静态站点生成器。如果你的仓库包含 Jekyll 项目文件，构建失败通常源于两个核心问题：_config.yml 配置文件编码错误，或使用了不受支持的第三方插件。
当收到构建失败通知时，可按以下流程排查：
- 检查 YAML 文件编码：确保
_config.yml文件使用 UTF-8 无 BOM 编码格式。带有 BOM（字节顺序标记）的 UTF-8 文件会导致 Jekyll 解析失败，错误信息常为YAML Exception: invalid byte sequence in UTF-8。可以使用代码编辑器（如 VS Code、Sublime Text）检查并转换编码。 - 排查第三方插件：GitHub Pages 仅支持其官方插件白名单中的插件。请暂时注释或移除
_config.yml中plugins或gems字段下的非白名单插件，提交测试是否构建成功。 - 彻底禁用 Jekyll：如果你的网站是纯静态文件，无需 Jekyll 处理，只需在仓库根目录放置一个名为
.nojekyll的空文件。GitHub 检测到此文件后，将完全跳过 Jekyll 构建流程，直接托管原始文件。
总结来说，GitHub Pages 部署受阻，往往不是流程复杂，而是细节疏漏：DNS 记录生效需要时间（最长可达48小时）、CNAME 文件格式有误、或本地与 GitHub 服务器上的 Jekyll 版本存在差异。一个非常实用的建议是：遇到问题时，第一时间前往仓库的 Settings → Pages 页面，查看最新的构建日志（Build logs），其中的错误信息是定位问题最直接的依据。
