关于发布源
您可以在将更改推送到特定分支时发布您的站点,也可以编写 GitHub Actions 工作流来发布您的站点。
如果您不需要控制站点的构建过程,我们建议您在将更改推送到特定分支时发布您的站点。您可以指定要使用的分支和文件夹作为发布源。源分支可以是仓库中的任何分支,源文件夹可以是源分支上的仓库根目录 (/
) 或源分支上的/docs
文件夹。每当将更改推送到源分支时,源文件夹中的更改都会发布到您的 GitHub Pages 站点。
如果您要使用 Jekyll 以外的构建过程,或者不希望使用专用分支来保存已编译的静态文件,我们建议您编写 GitHub Actions 工作流来发布您的站点。GitHub 提供了适用于常见发布场景的工作流模板,以帮助您编写工作流。
警告
即使站点的仓库是私有的(如果您的方案或组织允许),GitHub Pages 站点也能在互联网上公开访问。如果您的站点仓库中包含敏感数据,您可能需要在发布前删除这些数据。有关更多信息,请参阅“关于仓库”。
从分支发布
-
确保您要用作发布源的分支已存在于您的仓库中。
-
在 GitHub 上,导航到您的站点仓库。
-
在您的仓库名称下,单击 **设置**。如果您看不到“设置”选项卡,请选择****下拉菜单,然后单击**设置**。
-
在侧边栏的“代码和自动化”部分中,单击** Pages**。
-
在“构建和部署”下的“源”中,选择**从分支部署**。
-
在“构建和部署”下,使用分支下拉菜单并选择发布源。
-
可选:使用文件夹下拉菜单为发布源选择文件夹。
-
单击**保存**。
从分支发布的故障排除
注意
如果您的仓库包含符号链接,则需要使用 GitHub Actions 工作流发布您的站点。有关 GitHub Actions 的更多信息,请参阅“GitHub Actions 文档”。
注意
- 如果您是从分支发布,并且您的站点尚未自动发布,请确保拥有管理员权限和已验证电子邮件地址的用户已将更改推送到发布源。
- 使用
GITHUB_TOKEN
的 GitHub Actions 工作流推送的提交不会触发 GitHub Pages 构建。
如果您选择任何分支上的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**。
-
GitHub 将建议几个工作流模板。如果您已经有发布站点的workflow,则可以跳过此步骤。否则,请选择其中一个选项来创建 GitHub Actions 工作流。有关创建自定义工作流的更多信息,请参阅“创建自定义 GitHub Actions 工作流以发布您的站点”。
GitHub Pages 不会将特定工作流关联到 GitHub Pages 设置。但是,GitHub Pages 设置将链接到最近部署您的站点的 workflow 运行。
创建自定义 GitHub Actions 工作流以发布您的站点
有关 GitHub Actions 的更多信息,请参阅“GitHub Actions 文档”。
当您将站点配置为使用 GitHub Actions 发布时,GitHub 将建议适用于常见发布场景的工作流模板。工作流的一般流程是
- 每当对仓库的默认分支进行推送或从 Actions 选项卡手动运行工作流时触发。
- 使用
actions/checkout
操作检出仓库内容。 - 如果您的站点需要,请构建任何静态站点文件。
- 使用
actions/upload-pages-artifact
操作将静态文件上传为构件。 - 如果工作流是由对默认分支的推送触发的,请使用
actions/deploy-pages
操作部署构件。如果工作流是由拉取请求触发的,则会跳过此步骤。
工作流模板使用名为github-pages
的部署环境。如果您的仓库中尚未包含名为github-pages
的环境,则会自动创建该环境。我们建议您添加部署保护规则,以便只有默认分支才能部署到此环境。有关更多信息,请参阅“管理部署环境”。
注意
存储库文件中的CNAME
文件不会自动添加或删除自定义域名。您必须通过存储库设置或 API 配置自定义域名。更多信息,请参阅“管理您的 GitHub Pages 站点的自定义域名”和“GitHub Pages 的 REST API 端点”。
使用自定义 GitHub Actions 工作流发布时的故障排除
有关如何对 GitHub Actions 工作流进行故障排除的信息,请参阅“监控和排除工作流故障”。