排查 GitHub Pages 站点的 Jekyll 构建错误

您可以使用 Jekyll 构建错误消息来排查 GitHub Pages 站点的问题。

谁可以使用此功能？

GitHub Pages 适用于具有 GitHub Free 和组织的 GitHub Free 的公共存储库，以及具有 GitHub Pro、GitHub Team、GitHub Enterprise Cloud 和 GitHub Enterprise Server 的公共和专用存储库。 有关详细信息，请参阅 GitHub 的计划。

GitHub Pages 现在使用 GitHub Actions 来执行 Jekyll 构建。 使用分支作为构建源时，如果要使用内置的 Jekyll 工作流，则必须在存储库中启用 GitHub Actions。 或者，如果 GitHub Actions 不可用或已禁用，则将 .nojekyll 文件添加到源分支的根目录将绕过 Jekyll 构建过程并直接部署内容。 有关启用 GitHub Actions 的详细信息，请参阅“管理存储库的 GitHub Actions 设置”。

本文内容

排查构建错误

如果在本地或 GitHub 上构建 GitHub Pages 站点时发生 Jekyll 错误，你可以使用错误消息排查故障。 有关错误消息和如何查看的详细信息，请参阅“关于 GitHub Pages 站点的 Jekyll 构建错误”。

如果您收到一般错误消息，请检查常见问题。

  • 您使用的插件不受支持。 有关详细信息，请参阅“关于 GitHub 页面和 Jekyll”
  • 您的仓库已超过我们的仓库大小限制。 有关详细信息，请参阅“关于 GitHub 上的大文件”
  • 你更改了 _config.yml 文件中的 source 设置。 如果从分支发布站点，GitHub Pages 在生成过程中会覆盖此设置。
  • 已发布文件中的文件名包含不支持的冒号 (:)。

如果您收到特定的错误消息，请查看下面的错误消息疑难解答信息。

修复任何错误后，通过将更改发布到网站的源分支（如果是从分支发布的）或触发自定义 GitHub Actions 工作流（如果是使用 GitHub Actions 发布的）来触发其他版本。

Config 文件错误

此错误意味着网站生成失败，因为 _config.yml 文件包含语法错误。

要排除故障，请确保 _config.yml 文件遵循以下规则：

  • 使用空格代替制表符。
  • 在“:”后面为每个键/值对添加空格，例如 timezone: Africa/Nairobi。
  • 仅使用 UTF-8 字符。
  • 引用任何特殊字符（如 :），例如 title: "my awesome site: an adventure in parse errors"。
  • 对于多行值，用于 | 创建新行和 > 来忽略换行符。

若要识别任何错误，可以将 YAML 文件的内容复制并粘贴到 YAML Linter，例如 YAML 验证程序。

Note

If your repository contains symbolic links, you will need to publish your site using a GitHub Actions workflow. For more information about GitHub Actions, see GitHub Actions 文档.

日期不是有效的日期时间

此错误意味着站点上的某个页面包含无效的日期时间。

要排除故障，请搜索错误消息中的文件和文件布局，以调用任何与日期相关的 Liquid 过滤器。 确保传递给与日期相关的 Liquid 筛选器的任何变量在所有情况下都具有值，并且永远不会传递 nil 或 ""。 有关详细信息，请参阅 Liquid 文档中的筛选器。

文件在包含目录中不存在

此错误意味着代码引用了 _includes 目录中不存在的文件。

若要进行故障排除，请在 include 的错误消息中搜索文件，以查看你在哪些地方引用了其他文件，例如 {% include example_header.html %}。如果引用的任何文件不在 _includes 目录中，请将这些文件复制或移动到 _includes 目录 。

文件未采用正确的 UTF-8 编码

此错误意味着你使用了非拉丁字符（例如 日本語）但没有告诉计算机预期这些符号。

要排除故障，请通过在 _config.yml 文件中添加以下行来强制使用 UTF-8 编码：

encoding: UTF-8

高亮插件语言无效

此错误意味着你在配置文件中指定了除 Rouge 或 Pygments 之外的任何语法高亮插件。

要排除故障，请更新 _config.yml 文件以指定 Rouge 或 Pygments。 有关详细信息，请参阅“关于 GitHub 页面和 Jekyll”。

帖子日期无效

此错误意味着站点上的帖子在文件名或 YAML 前页中包含无效的日期。

要排除故障，请确保所有日期的 UTC 格式均为 YYYY-MM-DD HH:MM:SS， 并且都是实际日历日期。 若要指定与 UTC 偏移的时区，请使用格式 YYYY-MM-DD HH:MM:SS +/-TTTT，例如 2014-04-18 11:30:00 +0800。

如果在 _config.yml 文件中指定日期格式，请确保格式正确。

Sass 或 SCSS 无效

此错误意味着您的仓库包含内容无效的 Sass 或 SCSS 文件。

要排除故障，请查看指示 Sass 或 SCSS 无效的错误消息中包含的行号。 为防止以后出错，请在您的常用文本编辑器中安装 Sass 或 SCSS 语法检查插件。

子模块无效

此错误意味着您的仓库包含尚未正确初始化的子模块。

要排除故障，请先决定您是否真的想要使用子模块，它是 Git 项目内的 Git 项目； 子模块有时是意外创建的。

如果不想使用子模块，请删除子模块，将 PATH-TO-SUBMODULE 替换为子模块的路径：

git submodule deinit PATH-TO-SUBMODULE
git rm PATH-TO-SUBMODULE
git commit -m "Remove submodule"
rm -rf .git/modules/PATH-TO-SUBMODULE

如果要使用子模块，请确保在引用子模块时使用 https://（而不是 http://），并且子模块位于公共存储库中。

数据文件中的 YAML 无效

此错误意味着 _data 文件夹中的一个或多个文件包含无效的 YAML。

若要排查故障，请确保 _data 文件夹中的 YAML 文件遵循以下规则：

  • 使用空格代替制表符。
  • 在“:”后面为每个键/值对添加空格，例如 timezone: Africa/Nairobi。
  • 仅使用 UTF-8 字符。
  • 引用任何特殊字符（如 :），例如 title: "my awesome site: an adventure in parse errors"。
  • 对于多行值，用于 | 创建新行和 > 来忽略换行符。

若要识别任何错误，可以将 YAML 文件的内容复制并粘贴到 YAML Linter，例如 YAML 验证程序。

有关 Jekyll 数据文件的详细信息，请参阅 Jekyll 文档中的数据文件。

Markdown 错误

此错误意味着您的仓库包含 Markdown 错误。

要排除故障，请确保使用受支持的 Markdown 处理器。 有关详细信息，请参阅“使用 Jekyll 为 GitHub Pages 站点设置 Markdown 处理器”。

然后，确认错误消息中的文件使用有效的 Markdown 语法。 有关详细信息，请参阅 Daring Fireball 上的 Markdown：语法。