GitHub Pages 站点 Jekyll 构建错误排查

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

谁可以使用此功能？

GitHub Pages 可在使用 GitHub Free 和 GitHub Free for organizations 的公共存储库中使用，以及在使用 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 设置”。

本文内容

排查构建错误

如果 Jekyll 在本地或 GitHub 上构建 GitHub Pages 站点时遇到错误，您可以使用错误消息进行排查。有关错误消息及其查看方式的更多信息，请参阅“关于 GitHub Pages 站点的 Jekyll 构建错误”。

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

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

如果您收到特定错误消息，请查看以下错误消息的故障排除信息。

修复任何错误后，通过将更改推送到站点的源分支（如果您是从分支发布）或通过触发自定义 GitHub Actions 工作流（如果您使用 GitHub Actions 发布）来触发另一个构建。

配置文件错误

此错误表示您的站点由于 _config.yml 文件包含语法错误而无法构建。

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

  • 使用空格而不是制表符。
  • 在每个键值对的 : 后包含一个空格，例如 timezone: Africa/Nairobi。
  • 仅使用 UTF-8 字符。
  • 引用任何特殊字符，例如 :，例如 title: "my awesome site: an adventure in parse errors"。
  • 对于多行值，使用 | 创建换行符，并使用 > 忽略换行符。

要识别任何错误，您可以将 YAML 文件的内容复制并粘贴到 YAML lint 工具中，例如 YAML 验证器。

注意

如果您的存储库包含符号链接，您需要使用 GitHub Actions 工作流发布您的站点。有关 GitHub Actions 的更多信息，请参阅“GitHub Actions 文档”。

日期不是有效的日期时间

此错误表示您站点上的某个页面包含无效的日期时间。

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

includes 目录中不存在文件

此错误表示您的代码引用了 _includes 目录中不存在的文件。

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

文件未正确使用 UTF-8 编码

此错误表示您使用了非拉丁字符，如 日本語，但未告诉计算机预期这些符号。

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

encoding: UTF-8

无效的突出显示语言

此错误表示您在配置文件中指定了除 Rouge 或 Pygments 之外的任何语法突出显示器。

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

无效的帖子日期

此错误表示您站点上的某个帖子在文件名或 YAML 前端内容中包含无效的日期。

要进行故障排除，请确保所有日期都格式化为 YYYY-MM-DD HH:MM:SS（UTC 时间）并且是实际的日历日期。要使用相对于 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 lint 工具中，例如 YAML 验证器。

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

Markdown 错误

此错误表示您的存储库包含 Markdown 错误。

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

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

缺少 docs 文件夹

此错误表示您已选择分支上的docs文件夹作为发布源，但在该分支的存储库根目录中不存在docs文件夹。

要进行故障排除，如果您的docs文件夹意外移动，请尝试将docs文件夹移回您为发布源选择的那个分支的存储库根目录。如果docs文件夹意外删除，您可以：

  • 使用 Git 恢复或撤消删除操作。有关更多信息，请参阅 Git 文档中的git-revert。
  • 在您为发布源选择的那个分支的存储库根目录中创建一个新的docs文件夹，并将您站点的源文件添加到该文件夹中。有关更多信息，请参阅“创建新文件”。
  • 更改您的发布源。有关更多信息，请参阅“配置 GitHub Pages 站点的发布源”。

缺少子模块

此错误表示您的存储库包含不存在或尚未正确初始化的子模块。

要进行故障排除，首先确定您是否真的要使用子模块，子模块是 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

如果您确实要使用子模块，请初始化子模块。有关更多信息，请参阅Pro Git书籍中的Git 工具 - 子模块。

此错误表示您在_config.yml文件中使用了相对永久链接，GitHub Pages 不支持相对永久链接。

永久链接是指向您网站上特定页面的永久 URL。绝对永久链接以站点的根目录开头，而相对永久链接以包含所引用页面的文件夹开头。GitHub Pages 和 Jekyll 不再支持相对永久链接。有关永久链接的更多信息，请参阅 Jekyll 文档中的永久链接。

要进行故障排除，请从_config.yml文件中删除relative_permalinks行，并使用绝对永久链接重新格式化站点中的任何相对永久链接。有关更多信息，请参阅“编辑文件”。

'for'循环中的语法错误

此错误表示您的代码在 Liquid for循环声明中包含无效语法。

要进行故障排除，请确保错误消息中文件中的所有for循环都具有正确的语法。有关for循环的正确语法的更多信息，请参阅 Liquid 文档中的标签。

标签未正确关闭

此错误消息表示您的代码包含未正确关闭的逻辑标签。例如，{% capture example_variable %}必须由{% endcapture %}关闭。

要进行故障排除，请确保错误消息中文件中的所有逻辑标签都已正确关闭。有关更多信息，请参阅 Liquid 文档中的标签。

标签未正确终止

此错误表示您的代码包含未正确终止的输出标签。例如，{{ page.title }而不是{{ page.title }}。

要进行故障排除，请确保错误消息中文件中的所有输出标签都以}}结尾。有关更多信息，请参阅 Liquid 文档中的对象。

未知标签错误

此错误表示您的代码包含无法识别的 Liquid 标签。

要进行故障排除，请确保错误消息中文件中的所有 Liquid 标签都与 Jekyll 的默认变量匹配，并且标签名称中没有错别字。有关默认变量的列表，请参阅 Jekyll 文档中的变量。

不受支持的插件是无法识别的标签的常见来源。如果您通过在本地生成站点并将静态文件推送到 GitHub 来在您的站点中使用不受支持的插件，请确保插件没有引入 Jekyll 默认变量中不存在的标签。有关受支持插件的列表，请参阅“关于 GitHub Pages 和 Jekyll”。