关于 GitHub Pages 站点的 Jekyll 构建错误

如果在本地或 GitHub 上构建 GitHub Pages 站点发生 Jekyll 错误，你将收到一条错误消息，其中包含相关详细信息。

谁可以使用此功能？

GitHub Pages 适用于具有 GitHub Free 和组织的 GitHub Free 的公共存储库，以及具有 GitHub Pro、GitHub Team、GitHub Enterprise Cloud 和 GitHub Enterprise Server 的公共和专用存储库。

本文内容

关于 Jekyll 构建错误

如果从分支发布，则将更改推送到站点的发布源后，有时，GitHub Pages 不会尝试生成站点。

您使用部署密钥推送。如果要自动推送到站点的仓库，您可以改为设置计算机用户。有关详细信息，请参阅“管理部署密钥”。
您使用的是未配置为构建发布源的 CI 服务。例如，Travis CI 不会生成 gh-pages 分支，除非将分支添加到安全列表。有关详细信息，请参阅 Travis CI 上的自定义生成或 CI 服务的文档。

Note

对站点的更改在推送到 GitHub 后，最长可能需要 10 分钟才会发布。

如果 Jekyll 尝试构建站点但遇到错误，你将收到一条构建错误消息。 Jekyll 构建错误消息有两种主要类型。

“Page build warning（页面构建警告）”消息表示构建已成功完成，但您可能需要进行更改以防止将来出现问题。
“Page build failed（页面构建失败）”消息表示构建未能完成。如果 Jekyll 能够检测到失败的原因，您将看到描述性错误消息。

有关排查生成错误的详细信息，请参阅“排查 GitHub Pages 站点的 Jekyll 构建错误”。

查看 GitHub

上的存储库构建失败情况

你可以在站点存储库的“Settings”选项卡中查看生成失败（而不是生成警告）。****

在本地查看 Jekyll 构建错误消息

我们建议在本地测试站点，这样你可以在命令行上看到构建错误消息，并在更改推送到 GitHub 之前解决任何构建失败。有关详细信息，请参阅“使用 Jekyll 在本地测试 GitHub Pages 站点”。

在拉取请求中查看 Jekyll 构建错误消息

如果从分支发布，当创建拉取请求来更新 GitHub 上的发布源时，拉取请求的“Checks”选项卡上会显示生成错误消息。**** 有关详细信息，请参阅“关于状态检查”。

如果使用自定义 GitHub Actions 工作流进行发布，以在拉取请求中查看生成错误消息，则必须将工作流配置为在 pull_request 触发器上运行。执行此操作时，如果工作流已由 pull_request 事件触发，则建议跳过所有部署步骤。这样，无需将拉取请求中的更改部署到站点即可查看所有生成错误。有关详细信息，请参阅触发工作流的事件和对工作流和操作中的表达式求值。

通过电子邮件查看 Jekyll 构建错误

如果从分支发布，当将更改推送到 GitHub 上的发布源时，GitHub Pages 将尝试生成站点。如果构建失败，您将在您的主要电子邮件地址收到一封电子邮件。

Tip

只有在你的 GitHub Enterprise Server 实例上启用出站电子邮件支持时，才会收到电子邮件。更多信息请联系站点管理员。

如果使用自定义 GitHub Actions 工作流进行发布，以在拉取请求中接收有关生成错误的电子邮件，则必须将工作流配置为在 pull_request 触发器上运行。执行此操作时，如果工作流已由 pull_request 事件触发，则建议跳过所有部署步骤。这样，无需将拉取请求中的更改部署到站点即可查看所有生成错误。有关详细信息，请参阅触发工作流的事件和对工作流和操作中的表达式求值。

使用第三方 CI 服务查看拉取请求中的 Jekyll 构建错误消息

可以将第三方服务（如 Travis CI）配置为在每次提交后显示错误消息。

如果尚未在发布源的根目录中添加名为 Gemfile 的文件并包含以下内容：
```
source `https://rubygems.org`
gem `github-pages`
```
为您选择的测试服务配置站点仓库。例如，使用 Travis CI 在发布源的根目录中添加名为 .travis.yml 的文件并包含以下内容：
```
language: ruby
rvm:
  - 2.3
script: "bundle exec jekyll build"
```
您可能需要使用第三方测试服务激活仓库。更多信息请参阅测试服务的文档。