Skip to main content

此版本的 GitHub Enterprise 已停止服务 2022-10-12. 即使针对重大安全问题,也不会发布补丁。 为了获得更好的性能、更高的安全性和新功能,请升级到最新版本的 GitHub Enterprise。 如需升级帮助,请联系 GitHub Enterprise 支持

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

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

GitHub Pages 适用于具有 GitHub Free 和组织的 GitHub Free 的公共仓库,以及具有 GitHub Pro、GitHub Team、GitHub Enterprise Cloud 和 GitHub Enterprise Server 的公共和私有仓库。

排查构建错误

如果在本地或 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

高亮插件语言� 效

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

若要排除故障,请更新 _config.yml 文件以指定 RougePygments。 有关详细信息,请参阅“关于 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”。