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

排查构建错误

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

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

您使用的插件不受支持。有关详细信息，请参阅“关于 GitHub Pages 和 Jekyll。”
� 更改了 _config.yml 文件中的 source 设置。 GitHub Pages 在生成过程中会覆盖此设置。
已发布文件中的文件名包含不支持的冒号 (:)。

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

修复任何错误后，将更改推送到站点的发布源，以在 GitHub Enterprise Server 上触发另一个生成。

Config 文件错误

此错误意味着站点构建失败，� 为 _config.yml 文件包含语法错误。

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

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

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

日期不是有效的日期时间

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

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

文件在包含目录中不存在

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

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

文件是符号链接

此错误意味着� 的代� �引用了站点已发布文件中不存在的符号链接文件。

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

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

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

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

encoding: UTF-8

高亮插件语言� 效

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

若要排除故障，请更新 _config.yml 文件以指定 Rouge 或 Pygments。有关详细信息，请参阅“关于 GitHub Enterprise Server 和 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 文档中的“永久链接”。

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

符号链接不存在于站点的仓库中

此错误意味着� 的站点包含站点已发布文件中不存在的符号链接。有关符号链接的详细信息，请参阅 Wikipedia 上的“符号链接”。

要排除故障，请确定错误消息中的文件是否用于构建站点。如果否，或者您不希望文件成为符号链接，请� 除该文件。如果符号链接文件是生成站点的必需项，请确保符号链接引用的文件或目录存在于站点已发布文件中。若要包含外部资产，请考虑使用第三方包管理器，例如 Bower。

'for' 循环中的语法错误

此错误意味着代� �在 Liquid for 循环声明中包含� 效语法。

若要排除故障，请确保错误消息所指文件中的所有 for 循环都具有正确的语法。有关 for 循环的正确语法的详细信息，请参阅 Liquid 文档中的“迭代� �记”。

� �记未正确关闭

此错误消息意味着您的代� �包含未正确关闭的逻辑� �记。例如，{% capture example_variable %} 必须由 {% endcapture %} 关闭。

要排除故障，请确保错误消息所指文件中的所有逻辑� �记都正确关闭。有关详细信息，请参阅 Liquid 文档中的“Liquid � �记”。

� �记未正确终止

此错误意味着您的代� �包含未正确终止的输出� �记。例如，是 {{ page.title } 而不是 {{ page.title }}。

若要排除故障，请确保错误消息所指文件中的所有输出� �记都以 }} 终止。有关详细信息，请参阅 Liquid 文档中的“Liquid 对象”。

未知� �记错误

此错误意味着您的代� �包含� 法识别的 Liquid � �记。

要排除故障，请确保错误消息所指文件中的所有 Liquid � �记都与 Jekyll 的默认变量相匹配，并且� �记名称没有拼写错误。有关默认变量的列表，请参阅 Jekyll 文档中的“变量”。

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