GitHub Pages 使用教程：发布、更新与选择部署方式

GitHub Pages 把 GitHub 仓库中的静态文件发布为网站，适合项目文档、个人介绍、博客和前端演示。最短路径是在仓库中放一个 index.html，到 Settings → Pages 选择从现有分支发布，再通过 Pages 页面提供的网址访问。本文先用默认分支创建个人站点，之后再说明项目站点、gh-pages 分支和 GitHub Actions 的关系。GitHub Pages 官方说明将其定义为静态站点托管服务。

本文依据 2026-09-16 核对的 GitHub.com 官方文档编写。示例页面和操作路径只经过文档与本地静态检查，没有创建真实仓库或完成线上部署；文中的成功信号是读者实际操作后需要核对的结果。

Pages 能做什么

Pages 可以直接发布 HTML、CSS、JavaScript，也可以发布 Jekyll 或其他静态站点生成器的构建结果。文档、作品集、简历、博客、演示页都属于合适的用途。网站默认使用 github.io 地址，也可以按官方步骤绑定自己控制的域名。建站文档说明了静态文件、入口文件和构建方式。

Pages 不是持续运行的应用服务器：不能直接运行 PHP、Ruby、Python 等服务端代码，也不会自动提供数据库、账户登录或业务 API。浏览器中的 JavaScript 可以请求另行部署的 API，但后端服务、鉴权和数据安全要单独建设。官方使用限制还明确排除把 Pages 当作运行在线商店或商业 SaaS 的免费主机。

个人站点与项目站点

类型	仓库名称	默认地址	数量和用途
个人站点	`<用户名>.github.io`	`https://<用户名>.github.io/`	每个个人账号一个，适合主页或作品集
组织站点	`<组织名>.github.io`	`https://<组织名>.github.io/`	每个组织一个，适合组织主页
项目站点	普通项目仓库，例如 `hello-pages`	`https://<用户名>.github.io/hello-pages/`	每个仓库最多一个，适合项目文档或演示

上述是 GitHub.com 上未配置自定义域名的默认地址；组织、私有发布或自定义域名会影响实际 URL，以仓库 Settings → Pages 显示的地址为准。官方站点类型说明区分了个人、组织和项目站点。项目站点多了仓库名这一层路径，前端框架的资源 base、链接和图片地址需要匹配该路径；个人站点的根路径不能直接照搬到项目站点。

`gh-pages` 与其他发布方式

GitHub Pages 是最终提供网站的服务；gh-pages 是可能被选作发布源的普通 Git 分支名，并非开通服务的前提。同名的 npm gh-pages 包则是把构建结果推送到分支的第三方工具，也不是 Pages 服务。官方发布源配置提供两类入口：从分支及目录发布，或由自定义 GitHub Actions 工作流发布。

若只想展示一页手写 HTML，直接从分支发布就够了；若网站要先安装依赖、构建并运行检查，则考虑让 Actions 把构建结果交给 Pages。

发布源	网站文件从哪里来	适合情况
默认分支的 `/(root)`	直接读取分支根目录	少量静态页面；下方的个人站点实例
某分支的 `/docs`	读取该分支的 `docs` 目录	源码与文档同仓、文档文件已可直接发布
`gh-pages` 分支的 `/(root)`	读取专用分支中的发布文件	想把生成的网站文件与开发源码分开
GitHub Actions	工作流构建并上传静态文件包（artifact）供 Pages 部署	需要依赖安装、测试、框架构建或明确的部署控制

选择 Deploy from a branch 后，GitHub 仍可能在后台运行 Pages 构建与部署工作流；“从分支发布”不等于完全不经过 Actions。选择 GitHub Actions 作为 Source 时，自己的工作流负责提供部署 artifact，不要求创建 gh-pages 分支。若重点是维护专用发布分支，可阅读 gh-pages 分支使用教程；下方练习不需要创建该分支。

用默认分支发布第一个网站

准备一个已验证邮箱的 GitHub 个人账号，能够创建公开仓库并管理仓库 Pages 设置。GitHub Free 支持从公开仓库使用 Pages；私有仓库、站点访问控制和 Actions 使用额度应按当前方案核对。只在练习仓库放准备公开的内容，不要上传密码、令牌、未授权图片或个人资料。

下面用 <用户名> 表示你在 GitHub 的实际用户名，例如用户名是 octocat，仓库就应命名为 octocat.github.io。如果账号已有同名个人站点仓库，不要覆盖原有文件或修改原有 Pages 设置；另建一个公开项目仓库 hello-pages，使用相同的默认分支与根目录步骤，最终地址改为 https://<用户名>.github.io/hello-pages/。

创建仓库和首页

登录 GitHub 后创建公开仓库，名称填写 <用户名>.github.io，勾选初始化 README。创建成功后确认仓库有默认分支（通常叫 main），并确认当前分支就是该默认分支。官方 Pages 快速入门使用同样的仓库命名和分支发布路径。

在仓库 Code 页选择 Add file → Create new file，文件名填 index.html，在编辑器中加入以下完整内容：

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>我的 GitHub Pages 网站</h1>
    <p>这个页面由 GitHub Pages 发布。</p>
  </main>
</body>
</html>

选择 Commit changes，写明提交原因，确认文件提交到默认分支根目录。文件名必须是小写 index.html；分支发布也允许 index.md 或 README.md 作为入口，但这个练习明确使用 HTML，避免受 Markdown 主题与构建配置影响。建站文档要求入口文件位于选定发布目录的顶层。

开启 Pages 并核对网址

打开仓库 Settings → Pages，在 Build and deployment 中将 Source 设为 Deploy from a branch，Branch 选择当前默认分支，目录选择 /(root)，点击 Save。如果分支下拉框没有预期分支，返回 Code 页检查仓库是否已有至少一次提交、是否选错仓库。

回到 Pages 设置页，查看站点地址或 Visit site。仓库 Actions 中对应的 Pages 构建与部署运行成功后，访问 https://<用户名>.github.io/，应看到“我的 GitHub Pages 网站”。若使用备用项目仓库 hello-pages，地址应带 /hello-pages/。首次发布可能需要数分钟；提交成功、设置已保存与公开网址能够访问是三个不同的检查点，不要只看到提交就认定已发布。

更新和回退内容

保持发布源不变，在默认分支编辑 index.html 中的段落并提交。检查本次 Pages 部署运行成功，再刷新公开网址核对新文字。想增加 about.html 时，应将文件放在同一发布目录，并使用相对链接 href="about.html"；在项目站点中避免把站内资源写成忽略仓库名前缀的根路径。

如果更新后网站出现问题，先在 Actions 中查找失败的部署以及对应提交。对这个单文件练习，可恢复上一份已知正确的 index.html 内容并再次提交，等新的部署成功后再核对公开网页；不要直接删除整个仓库或修改域名记录作为回退手段。

构建工具与 Actions 发布

从分支发布时，GitHub Pages 默认使用 Jekyll 处理站点。如果使用 Vite、VitePress、MkDocs 等工具生成最终静态文件，应该区分源文件和可发布的构建目录：Pages 需要入口文件位于最终发布目录的顶层，而不是把尚未构建的组件源码当作网页。官方建站文档建议非 Jekyll 构建器使用自定义 Actions；若坚持从分支发布，可以在发布源根目录加入空的 .nojekyll，并在其他地方先完成构建。

对新的构建型站点，按官方 Actions 发布流程操作：在 Settings → Pages 将 Source 改为 GitHub Actions，选择适合所用构建器的工作流模板，核对构建命令及输出目录后提交工作流。部署链一般包括检出源码、构建、使用 actions/upload-pages-artifact 上传构建产物（artifact，即供 Pages 部署的静态文件包），再由 actions/deploy-pages 发布。部署 job 至少需要 pages: write 与 id-token: write，并使用 github-pages 环境；如果只允许默认分支部署，还需在该环境中另外配置仅允许默认分支的部署保护规则。环境名称本身不提供这项限制。自定义工作流文档说明了权限与 artifact 要求。

成功信号仍是 Actions 工作流与公开网址同时通过检查。切换一个已有站点的 Source 会改变发布链，应先确认新工作流已能生成完整的静态目录并有回退方案，不能仅因为需要自动构建就盲目改写当前站点设置。工作流模板和 action 版本会更新，复制之前以当时的官方模板为准。

自定义域名与 HTTPS

默认 github.io 地址已足够使用。想绑定自己的域名时，建议先按官方所有权验证步骤在账号设置中验证域名所有权，以降低域名被接管的风险；这一步不同于后面的 DNS 解析检查。然后在仓库 Settings → Pages → Custom domain 登记域名，再按官方域名配置步骤到 DNS 服务商添加记录：子域名通常用 CNAME 指向 <用户名>.github.io，根域名按官方当前记录要求配置。完成 DNS 解析核对后，检查 HTTPS 状态并在可用时启用 Enforce HTTPS。

先在 Pages 中登记域名，再配置 DNS 指向。仅提交 CNAME 文件不会替代 Pages 设置；直接把未登记的子域名指向 GitHub Pages 还可能造成域名被未经授权的第三方占用的风险。若个人站点设置了自定义域名，同一账号下未单独配置域名的项目站点地址也可能随之变化，更新导航和构建路径前要核对 Pages 页面给出的实际 URL。官方域名说明解释了这层继承关系。

权限、公开性和使用限制

仓库私有与网站私有不是同一个设置。GitHub Free 下选择公开仓库是最简单的学习路径；付费方案允许在私有仓库使用 Pages，但不能据此推断网站仅对仓库成员可见。私有发布的访问控制主要面向符合条件的 GitHub Enterprise Cloud 组织项目站点，需要组织配置并检查最终站点可见性；个人站点不能直接套用这个组织能力。站点可见性文档列出了适用边界。

按 2026-09-16 的官方限制，源仓库建议不超过 1 GB，发布站点不能超过 1 GB，部署超过 10 分钟会超时；月流量和每小时构建次数还有软限制，使用自定义 Actions 构建的计量条件有所不同。把大文件下载、频繁动态请求或商业交易放到 Pages 上，不符合静态文档与展示站点的用途。发布前还应检查版权和敏感信息：已经公开的文件不能因为后续从页面上删除就视为从网络和 Git 历史中消失。

常见故障排查

现象	核对顺序
首页 404	看 Pages 地址是否正确、部署是否成功，再核对发布分支/目录及顶层 `index.html` 的大小写
仓库里有文件但站点没有更新	查看提交所在分支与本次 Pages 工作流；等待部署成功后再检查缓存
首页能看，样式或图片 404	对项目站点核对 `/<仓库名>/` 路径、资源的相对链接及构建器 `base` 配置
Actions 失败	打开失败 job 的日志，检查构建命令、依赖、artifact 目录、入口文件和部署权限
自定义域名不能访问	先核对 Pages 中登记的域名，再检查 DNS、域名验证和 HTTPS 状态；不要只改 DNS
私有仓库无法启用或站点意外公开	核对账号方案、组织策略与 Pages 站点可见性，不凭仓库可见性推断网站权限

GitHub 官方 404 排障还列出了 GitHub 服务状态、DNS、浏览器缓存和入口文件位置等检查项。处理故障时，先区分“文件未提交”“构建/部署失败”和“部署成功但 URL 或资源路径错误”，再改变配置。

GitHub Pages 使用教程：发布、更新与选择部署方式 ​

Pages 能做什么 ​

个人站点与项目站点 ​

gh-pages 与其他发布方式 ​

用默认分支发布第一个网站 ​

创建仓库和首页 ​

开启 Pages 并核对网址 ​

更新和回退内容 ​

构建工具与 Actions 发布 ​

自定义域名与 HTTPS ​

权限、公开性和使用限制 ​

常见故障排查 ​

参考资料 ​