跳至主要内容

为您的 GitHub Pages 网站配置发布源

您可以将 GitHub Pages 网站配置为在将更改推送到特定分支时发布,或者您可以编写 GitHub Actions 工作流来发布您的网站。

谁可以使用此功能?

拥有仓库管理员或维护者权限的人员可以为 GitHub Pages 网站配置发布源。

GitHub Pages 在使用 GitHub Free 和 GitHub Free for organizations 的公共仓库中可用,在使用 GitHub Pro、GitHub Team、GitHub Enterprise Cloud 和 GitHub Enterprise Server 的公共和私有仓库中可用。有关更多信息,请参阅“GitHub 的计划”。

从 2024 年 6 月 30 日起,所有 GitHub Pages 构建都将使用 GitHub Actions。无需进行其他更改,但必须在您的仓库中启用 GitHub Actions 才能继续构建。有关启用 GitHub Actions 的更多信息,请参阅“管理仓库的 GitHub Actions 设置”。

关于发布源

您可以将网站发布到特定分支的更改被推送时,或者您可以编写一个 GitHub Actions 工作流来发布您的网站。

如果您不需要对网站的构建过程进行任何控制,我们建议您在更改被推送到特定分支时发布您的网站。您可以指定要使用哪个分支和文件夹作为您的发布源。源分支可以是您存储库中的任何分支,源文件夹可以是源分支上的存储库根目录 (/) 或源分支上的 /docs 文件夹。每当更改被推送到源分支时,源文件夹中的更改将被发布到您的 GitHub Pages 网站。

如果您想使用除 Jekyll 之外的构建过程,或者您不想使用专用分支来保存您的已编译静态文件,我们建议您编写一个 GitHub Actions 工作流来发布您的网站。GitHub 提供了针对常见发布场景的入门工作流,以帮助您编写工作流。

警告:即使网站的存储库是私有的,GitHub Pages 网站也将在互联网上公开可用。如果您在网站的存储库中包含敏感数据,您可能需要在发布之前删除这些数据。有关更多信息,请参阅 "关于存储库."

从分支发布

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

  2. 在 GitHub 上,导航到您的网站的存储库。

  3. 在您的存储库名称下,单击 设置。如果您看不到“设置”选项卡,请选择 下拉菜单,然后单击 设置

    Screenshot of a repository header showing the tabs. The "Settings" tab is highlighted by a dark orange outline.

  4. 在侧边栏的“代码和自动化”部分,单击 Pages

  5. 在“构建和部署”下,在“源”下,选择 从分支部署

  6. 在“构建和部署”下,使用分支下拉菜单并选择一个发布源。

    Screenshot of Pages settings in a GitHub repository. A menu to select a branch for a publishing source, labeled "None," is outlined in dark orange.

  7. 您可以选择使用文件夹下拉菜单选择用于发布源的文件夹。

    Screenshot of Pages settings in a GitHub repository. A menu to select a folder for a publishing source, labeled "/(root)," is outlined in dark orange.

  8. 点击保存

从分支发布的故障排除

注意:如果您的仓库包含符号链接,则需要使用 GitHub Actions 工作流程发布您的网站。有关 GitHub Actions 的更多信息,请参阅“GitHub Actions 文档”。

说明:

  • 如果您是从分支发布,并且您的网站尚未自动发布,请确保具有管理员权限和已验证电子邮件地址的用户已将代码推送到发布源。

  • 使用GITHUB_TOKEN的 GitHub Actions 工作流程推送的提交不会触发 GitHub Pages 构建。

如果您在任何分支上选择docs文件夹作为您的发布源,然后从您的仓库中删除该分支上的/docs文件夹,您的网站将无法构建,并且您将收到有关缺少/docs文件夹的页面构建错误消息。有关更多信息,请参阅“GitHub Pages 网站的 Jekyll 构建错误故障排除”。

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

要查找构建或部署的潜在错误,您可以通过查看仓库的工作流程运行来检查 GitHub Pages 网站的工作流程运行。有关更多信息,请参阅“查看工作流程运行历史记录”。有关如何在发生错误时重新运行工作流程的更多信息,请参阅“重新运行工作流程和作业”。

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

要将您的网站配置为使用 GitHub Actions 发布

  1. 在 GitHub 上,导航到您的网站的存储库。

  2. 在您的存储库名称下,单击 设置。如果您看不到“设置”选项卡,请选择 下拉菜单,然后单击 设置

    Screenshot of a repository header showing the tabs. The "Settings" tab is highlighted by a dark orange outline.

  3. 在侧边栏的“代码和自动化”部分,单击 Pages

  4. 在“构建和部署”下,在“源”下,选择GitHub Actions

  5. GitHub 将建议几个入门工作流程。如果您已经有一个工作流程来发布您的网站,您可以跳过此步骤。否则,选择其中一个选项来创建 GitHub Actions 工作流程。有关创建自定义工作流程的更多信息,请参阅“创建自定义 GitHub Actions 工作流程以发布您的网站”。

    GitHub Pages 不会将特定工作流程与 GitHub Pages 设置关联。但是,GitHub Pages 设置会链接到最近部署您网站的工作流程运行。

创建自定义 GitHub Actions 工作流程以发布您的网站

有关 GitHub Actions 的更多信息,请参阅“GitHub Actions 文档”。

当您将网站配置为使用 GitHub Actions 发布时,GitHub 会建议用于常见发布场景的入门工作流程。工作流程的一般流程是

  1. 在每次推送到存储库的默认分支或从 Actions 选项卡手动运行工作流程时触发。
  2. 使用 actions/checkout 操作检出存储库内容。
  3. 如果您的网站需要,请构建任何静态站点文件。
  4. 使用 actions/upload-pages-artifact 操作将静态文件作为工件上传。
  5. 如果工作流程是由推送到默认分支触发的,请使用 actions/deploy-pages 操作部署工件。如果工作流程是由拉取请求触发的,则会跳过此步骤。

入门工作流程使用名为 github-pages 的部署环境。如果您的存储库中还没有名为 github-pages 的环境,则会自动创建该环境。我们建议您添加部署保护规则,以便只有默认分支才能部署到此环境。有关更多信息,请参阅“使用环境进行部署”。

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

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

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