排查构建错误
如果在本地或 GitHub Enterprise Server 上构建 GitHub Pages 站点时发生 Jekyll 错误,您可以使用错误消息排查故障。 有关错误消息和如何查看的详细信息,请参阅“关于 GitHub Pages 站点的 Jekyll 构建错误”。
如果您收到一般错误消息,请检查常见问题。
- 您使用的插件不受支持。 有关详细信息,请参阅“关于 GitHub 页面和 Jekyll”。
- 你更改了
_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 文档中的筛选器。
文件在包含目录中不存在
此错误意味着代码引用了 _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 文档中的标记。
标记未正确终止
此错误意味着您的代码包含未正确终止的输出标记。 例如,是 {{ page.title }
而不是 {{ page.title }}
。
若要排除故障,请确保错误消息所指文件中的所有输出标记都以 }}
终止。 有关详细信息,请参阅 Liquid 文档中的对象。
未知标记错误
此错误意味着您的代码包含无法识别的 Liquid 标记。
要排除故障,请确保错误消息所指文件中的所有 Liquid 标记都与 Jekyll 的默认变量相匹配,并且标记名称没有拼写错误。 有关默认变量的列表,请参阅 Jekyll 文档中的变量。
不受支持的插件是无法识别标记的常见来源。 如果您通过在本地生成站点并将静态文件推送到 GitHub Enterprise Server 的方法在站点中使用不受支持的插件,请确保该插件未引入 Jekyll 默认变量中没有的标记。 有关支持的插件的列表,请参阅“关于 GitHub 页面和 Jekyll”。