排查 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 文档中的“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：语法”。

缺少 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 文档中的“永久链接”。

要排除故障，请移除 relative_permalinks 文件中的 _config.yml 行，并将网站中的任何相对永久链接重新格式化为绝对永久链接。 有关详细信息，请参阅“编辑文件”。

'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 页面和 Jekyll”。