对 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 的计划”。

从 2024 年 6 月 30 日起，所有 GitHub Pages 构建都将使用 GitHub Actions。无需进行其他更改，但必须在你的存储库中启用 GitHub Actions 才能继续构建。有关启用 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 linter 中，例如 YAML Validator。

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

日期不是有效的日期时间

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

要进行故障排除，在错误消息中搜索文件以及该文件的布局以查找对任何与日期相关的 Liquid 过滤器的调用。确保传递到与日期相关的 Liquid 过滤器的任何变量在所有情况下都有值，并且永远不要传递 nil 或 ""。有关更多信息，请参阅 Liquid 文档中的“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 前置内容中包含无效日期。

要进行故障排除，请确保所有日期均采用 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 linter。

无效的子模块

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

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

有关 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 文档中的“Liquid 标签”。

标签未正确终止

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

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

未知标签错误

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

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

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