Skip to main content

配置 GitHub Pages 站点的发布源

可以将 GitHub Pages 站点配置为在将更改推送到特定分支时进行发布,也可以编写 GitHub Actions 工作流来发布站点。

Who can use this feature

People with admin or maintainer permissions for a repository can configure a publishing source for a GitHub Pages site.

GitHub Pages 适用于具有 GitHub Free 和组织的 GitHub Free 的公共仓库,以及具有 GitHub Pro、GitHub Team、GitHub Enterprise Cloud 和 GitHub Enterprise Server 的公共和私有仓库。 有关详细信息,请参阅“GitHub 的产品”。

关于发布源

可以在将更改推送到特定分支时发布站点,也可以编写 GitHub Actions 工作流来发布站点。

如果不需要对站点的生成过程进行任何控制,则建议在将更改推送到特定分支时发布站点。 可以指定要用作发布源的分支和文件夹。 源分支可以是存储库中的任何分支,源文件夹可以是源分支上的存储库根目录 (/),也可以是源分支上的 /docs 文件夹。 将更改推送到源分支时,源文件夹中的更改将发布到 GitHub Pages 站点。

如果想使用 Jekyll 以外的生成过程,或者不想使用专用分支来保存已编译的静态文件,则建议编写 GitHub Actions 工作流来发布站点。 GitHub 为常见的发布方案提供入门工作流,以帮助编写工作流。

警告:GitHub Pages 站点可以在 Internet 上公开,即使该站点的存储库是私有的。 如果站点的存储库中有敏感数据,你可能想要在发布前删除数据。 有关详细信息,请参阅关于存储库

从分支进行发布

  1. 确保你要用作发布源的分支已经存在于你的存储库中。

  2. 在 GitHub 上,导航到站点的仓库。 1. 在存储库名称下,单击 “设置”。 “存储库设置”按钮

  3. In the "Code and automation" section of the sidebar, click Pages.

  4. 在“生成和部署”的“源”下,选择“从分支进行部署”。

  5. 在“生成和部署”的“分支”下,使用“无”或“分支”下拉菜单并选择发布源 。

    用于选择发布源的下拉菜单

  6. (可选)使用下拉菜单选择发布源的文件夹。 用于选择发布源文件夹的下拉菜单

  7. 单击“ 保存”。 用于保存对发布源设置的更改的按钮

从分支进行发布疑难解答

注意:如果从分支进行发布且站点尚未自动发布,请确保具有管理员权限和经验证的电子邮件地址的人员已将站点推送到发布源。

如果选择任意分支上的 docs 文件夹作为发布源,稍后从存储库中的该分支中删除 /docs 文件夹,则站点不会生成,并且你将收到缺失 /docs 文件夹的页面生成错误消息。 有关详细信息,请参阅“对 GitHub Pages 站点的 Jekyll 生成错误进行故障排除”。

GitHub Pages 站点将始终使用 GitHub Actions 工作流程运行进行部署,即使您已将 GitHub Pages 站点配置为使用其他 CI 工具构建也是如此。 大多数外部 CI 工作流通过将生成输出提交到存储库的 gh-pages 分支来“部署”到 GitHub Pages,且通常包含 .nojekyll 文件。 发生这种情况时, GitHub Actions 工作流程将检测分支不需要构建步骤的状态,并且仅执行将站点部署到 GitHub Pages 服务器所需的步骤。

若要查找构建或部署的潜在错误,可以通过查看仓库的工作流程运行来检查 GitHub Pages 站点的工作流程运行情况。 有关详细信息,请参阅“查看工作流运行历史记录”。 有关如何在出现错误时重新运行工作流的详细信息,请参阅“重新运行工作流和作业”。

使用自定义 GitHub Actions 工作流进行发布

注意:使用自定义 GitHub Actions 工作流发布 GitHub Pages 站点处于测试阶段,可能会发生变化。

若要将站点配置为使用 GitHub Actions 进行发布,请执行以下操作:

  1. 在 GitHub 上,导航到站点的仓库。 1. 在存储库名称下,单击 “设置”。 “存储库设置”按钮

  2. In the "Code and automation" section of the sidebar, click Pages.

  3. 在“生成和部署”的“源”下,选择“GitHub Actions”。

  4. GitHub 将推荐多个入门工作流。 如果已有用于发布站点的工作流,可跳过此步骤。 否则,请选择其中一个选项来创建 GitHub Actions 工作流。 有关创建自定义工作流的详细信息,请参阅“创建自定义 GitHub Actions 工作流以发布站点”。

    GitHub Pages 不会将特定工作流与 GitHub Pages 设置相关联。 但 GitHub Pages 设置将链接到最近部署你的站点的工作流运行。

创建自定义 GitHub Actions 工作流以发布站点

有关 GitHub Actions 的详细信息,请参阅“Actions”。

将站点配置为使用 GitHub Actions 进行发布时,GitHub 将针对常见发布方案推荐入门工作流。 工作流的一般流程如下:

  1. 在推送到存储库的默认分支时,或者在已打开、已重新打开或已更新针对默认分支的拉取请求时触发。
  2. 使用 actions/checkout 操作签出存储库内容。
  3. 如果站点需要,请生成任何静态站点文件。
  4. 使用 actions/upload-pages-artifact 操作将静态文件作为项目上传。
  5. 如果推送到默认分支触发了工作流,请使用 actions/deploy-pages 操作来部署项目。 如果拉取请求触发了工作流,则跳过此步骤。

入门工作流使用名为 github-pages 的部署环境。 如果存储库尚未包含名为 github-pages 的环境,则自动创建该环境。 建议添加环境保护规则,确保仅默认分支可部署到该环境。 有关详细信息,请参阅“使用环境进行部署”。

注意:存储库文件中的 CNAME 文件不会自动添加或删除自定义域。 必须通过存储库设置或 API 配置自定义域。 有关详细信息,请参阅“管理 GitHub Pages 站点的自定义域”和 Pages API 参考文档

使用自定义 GitHub Actions 工作流进行发布故障排除

有关如何对 GitHub Actions 工作流进行故障排除的信息,请参阅“关于监视和故障排除”。