gh-pages 分支使用教程：用 GitHub Pages 发布静态网站
gh-pages 是经常用来保存网站发布文件的 Git 分支名。把静态页面放到这个分支，并在仓库的 Pages 设置中选中该分支，就可以将项目网站发布到 https://<用户名>.github.io/<仓库名>/。GitHub Pages 是托管网站的服务，gh-pages 只是其中一种发布源：站点也可以从其他分支或 GitHub Actions 发布。官方发布源文档同时支持分支和自定义工作流。
本文以个人账号下的公开项目仓库 hello-gh-pages 为例，从浏览器创建分支、写入 index.html，再检查部署结果。操作依据于 2026-09-16 核对的官方文档；没有创建真实仓库或实际部署站点，结果描述是读者操作时应核对的成功信号，而非本次运行实测。
三个容易混淆的名称
| 名称 | 实际是什么 | 是否必须使用 |
|---|---|---|
| GitHub Pages | 将仓库中的静态文件发布为网站的服务 | 要发布到 GitHub 提供的网站时需要 |
gh-pages 分支 | 仓库中的一个普通 Git 分支，可专门存放发布文件 | 不必须；可选其他分支或 Actions |
npm gh-pages 包 | 将构建结果推送到指定远程分支的第三方工具 | 不必须；不是 GitHub Pages 服务本身 |
GitHub 官方在说明外部 CI 工具时提到：不少工具会把构建结果提交到 gh-pages 分支。MkDocs 的部署文档把 gh-pages 作为项目文档的默认部署分支；npm 包登记信息则把同名工具描述为“发布到 GitHub 的 gh-pages 分支，或其他远程的其他分支”。所以这个名字来自常见约定，不是启用 Pages 的特殊开关。
能发布什么，不能运行什么
GitHub Pages 托管 HTML、CSS 和 JavaScript 等静态输出，适合项目说明、API 文档、个人作品集、简历、博客和前端演示页。静态站点生成器也可以先把 Markdown 或前端源码构建成页面，再交给 Pages。GitHub Pages 不会作为通用后端服务器运行 PHP、数据库或持续运行的 API 进程；需要登录、持久化写入或服务端计算时，应另选后端服务，并设计访问控制。官方产品说明明确将 Pages 定义为静态站点托管。
Pages 不是无限制的网站托管服务。官方使用限制列出站点体积、部署时长、流量和构建频率等边界，并说明不能把 Pages 当作运行在线商店或商业 SaaS 的免费主机。发布之前，还要确认要展示的内容有权公开，不能把密码、令牌、客户资料或内部配置放到发布分支。
发布前准备
- 一个已验证邮箱的 GitHub 个人账号，并拥有目标仓库的 Pages 配置权限。没有账号时，先按照账号创建说明完成注册。
- 一个名为
hello-gh-pages的公开仓库，创建时勾选 README，以便产生初始提交和默认分支。个人免费方案下，Pages 可用于公开仓库；私有仓库的 Pages 可用性与付费方案、组织设置有关，按当前方案核对。 - 仓库里不能放真实密钥。公开仓库及其发布站点都面向互联网，切换分支不会改变这一点。
这里选择“项目站点”，地址末尾包含仓库名。若仓库恰好叫 <用户名>.github.io，则属于用户站点，默认地址是 https://<用户名>.github.io/；官方站点类型说明区分了两者。后续示例一律使用项目站点，避免混淆 URL 路径。
第一次发布：分支根目录
创建发布分支
进入 hello-gh-pages 仓库的 Code 页，在文件列表上方打开分支选择器，输入 gh-pages，选择从当前默认分支创建新分支。切换后，页面上的当前分支应显示 gh-pages。如果仓库是空仓库，先在默认分支创建 README 并提交；官方发布源步骤要求准备选为发布源的分支已经存在。
分支不会凭名字自动成为网站。此时还需要入口文件，并在 Pages 设置中选择发布源。
添加首页文件
确认当前分支仍是 gh-pages，选择 Add file → Create new file，文件名填 index.html，内容填入以下完整示例：
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>我的第一个 GitHub Pages 网站</title>
</head>
<body>
<main>
<h1>网站已经发布</h1>
<p>这个页面来自 hello-gh-pages 仓库的 gh-pages 分支。</p>
</main>
</body>
</html>点击 Commit changes，填写说明并将文件提交到 gh-pages。回到分支文件列表，确认 index.html 位于仓库根目录，而非子文件夹。对于分支发布，官方建站说明要求 index.html、index.md 或 README.md 位于所选发布目录的顶层。这个示例明确使用 index.html，不依赖 README 被自动转换为主页。
选择 Pages 发布源
在该仓库打开 Settings → Pages。在 Build and deployment 下，将 Source 设为 Deploy from a branch；在 Branch 中选择 gh-pages，目录选择 /(root)，保存。这里是对该仓库的设置，不是在个人账号主页创建一个同名项目。
Pages 页面应显示预期的站点地址。查看仓库 Actions 中 Pages 的构建与部署运行状态，等待成功后打开 https://<用户名>.github.io/hello-gh-pages/，将 <用户名> 换为自己的真实账号名。看到“网站已经发布”，并且页面地址包含 /hello-gh-pages/，才说明从分支到网站的链路完成。首次发布和后续更新可能需要一段时间，不应把刚提交后立即出现的 404 当作最终结果。官方建站说明还给出了在设置页访问站点、检查工作流运行的路径。
修改网站与管理两条分支
若要改首页，在 Code 页先切到 gh-pages，编辑 index.html 并提交。检查 Pages 部署运行成功后刷新站点；如果仍显示旧内容，核对提交所在分支、Pages 的 Source/Branch 设置及浏览器缓存。只修改默认分支的 README，不会自动改变以 gh-pages 为发布源的网站。
| 分支 | 此示例中的用途 | 通常应放什么 |
|---|---|---|
默认分支（如 main） | 项目开发和说明 | 源码、README、构建配置 |
gh-pages | Pages 的发布源 | index.html 及网站所需的静态文件 |
小型纯 HTML 网站可以直接维护 gh-pages。若网站由 MkDocs、Vite 或其他工具构建，通常应在默认分支维护源文件，把构建产物交给部署工具或 Actions；别在两条分支分别手改同一份生成内容，否则下一次构建可能覆盖手工修改。
构建型网站怎样选择发布方式
| 方式 | 做法 | 适合情况 |
|---|---|---|
| 分支手工发布 | 直接编辑 gh-pages，Pages 选 /(root) | 少量无需构建的 HTML、CSS、JS |
| 工具推送到分支 | 从源码构建后将结果提交到 gh-pages | 已使用工具提供的分支部署命令，希望保留产物分支 |
| GitHub Actions 发布 | 工作流构建并上传 Pages artifact | 框架构建、依赖安装和自动检查较多的项目，无须维护产物分支 |
例如，MkDocs 用户在已经安装 MkDocs、配置好项目并检查本地构建结果后，可以在源码仓库运行 mkdocs gh-deploy。MkDocs 文档说明该命令会构建文档并通过 ghp-import 推送到默认的 gh-pages 分支；执行前应确认远程仓库和目标分支，因为命令会直接推送。这里介绍的是 MkDocs 的约定，不是所有 Pages 网站的必经步骤。npm 的 gh-pages 包是另一个可用于发布构建目录的工具，使用前还需要单独确认目标目录及仓库权限。
对于非 Jekyll 的静态站点生成器，GitHub 官方建议优先考虑自定义 Actions 工作流。分支发布默认可能经过 Jekyll 处理；若使用其他构建器并仍从分支发布，可以在发布源根目录加入空的 .nojekyll 文件来关闭这一步，避免以下划线开头的产物被 Jekyll 处理。Actions 模式下应在 Source 选择 GitHub Actions，由工作流构建、上传和部署 artifact，不要求存在 gh-pages 分支；官方发布源文档分别说明了两种配置路径。
常见故障排查
| 现象 | 定位与处理 |
|---|---|
Pages 的分支列表没有 gh-pages | 确认已在仓库创建分支，并且至少有一次提交；刷新设置页 |
| 访问站点显示 404 | 核对仓库名和 URL 中的 /hello-gh-pages/；检查 Source、分支、目录及部署运行是否成功 |
| 网站没有首页 | 确认 index.html 位于 gh-pages 的根目录且拼写正确；若选 /docs，入口必须在该目录顶层 |
| HTML 出现但样式、图片或脚本 404 | 项目站点以仓库名为路径前缀；检查资源是相对路径还是为该前缀配置了正确的构建 base |
| 提交成功但网站不更新 | 在 Actions 查看 Pages 构建/部署的具体错误；确认提交到了发布分支，等待部署结束后再排查缓存 |
| 私有仓库不能启用 Pages | 核对账号方案、仓库及组织策略；免费个人账号先用不含敏感内容的公开仓库练习 |
如果发布分支意外包含私密内容，不要仅删除页面后认为风险消失：仓库历史和已发布内容可能已经被访问。应先撤销相关凭据，再按组织流程处理历史及缓存。实际站点是否可见，还应从未登录的浏览器窗口检查；私有仓库中的 Pages 网站也不能当然视为私有网站，公开性取决于产品方案及访问控制配置。
自定义域名与运行边界
默认地址足以完成练习。配置自己的域名时，需要在仓库 Pages 设置中添加域名，并按官方域名文档设置相应 DNS、验证和 HTTPS；单独提交一个 CNAME 文件并不等于已在设置中完成域名绑定。设置前核对域名所有权，删除旧站点时也要清理不再使用的 DNS 记录，避免域名被接管。
日常维护时，至少检查三处：源码提交或发布分支的最新文件、Pages 对应的部署运行、公开网址的首页及静态资源。页面能在仓库里看到，只证明文件已提交；部署运行成功且公开网址返回正确内容，才说明读者能够访问网站。