GitHub Actions中Jekyll报undefined method `yaml_file?'错误求助

问题场景 #

使用搭载Jekyll-Pandoc插件的自定义Jekyll Docker镜像构建GitHub Pages网站，本地运行正常，此前GitHub Actions调用该镜像也能正常工作，但近期触发构建时出现如下错误：

Jekyll Feed: Generating feed for posts
                    ------------------------------------------------
      Jekyll 4.3.2   Please append `--trace` to the `build` command 
                     for any additional information or backtrace. 
                    ------------------------------------------------
/usr/local/lib/ruby/2.7.0/forwardable.rb:233:in `yaml_file?': undefined method `yaml_file?' for #<Jekyll::Page @relative_path="index.md"> (NoMethodError)

问题分析 #

这个错误核心是Jekyll Feed插件调用yaml_file?方法时，Jekyll::Page对象不存在该方法，大概率是依赖版本兼容性问题：

• Jekyll Feed插件版本与Jekyll 4.3.2不兼容，插件代码调用了Jekyll核心已移除/未公开的方法
• 自定义Docker镜像中的依赖（Ruby、Jekyll核心、各插件）更新后出现冲突
• Jekyll-Pandoc与Jekyll Feed插件之间存在隐性兼容性冲突

解决方案 #

1. 锁定Jekyll Feed兼容版本 #

Jekyll 4.3.2需搭配兼容的Jekyll Feed版本（如v0.17.0及以上），在项目Gemfile中明确指定：

gem "jekyll-feed", "~> 0.17.0"

同步更新自定义Docker镜像中的依赖，确保安装指定版本的插件。

2. 排查插件冲突 #

临时禁用Jekyll Feed插件（在_config.yml中注释相关配置），重新触发GitHub Actions构建：

# plugins:
#   - jekyll-feed
#   - jekyll-pandoc

若构建恢复正常，说明问题出在Jekyll Feed与其他组件的兼容性上，可尝试升级Jekyll Feed到最新兼容版本，或调整Jekyll核心版本。

3. 调整Jekyll核心版本 #

既然此前构建正常，当前Jekyll 4.3.2可能引入了兼容性问题，可尝试：

• 降级到之前能正常工作的Jekyll版本（如4.2.x）
• 升级到Jekyll 4.x系列最新稳定版，修复已知方法调用问题

4. 启用详细错误追踪 #

在GitHub Actions的构建命令中添加--trace参数，获取完整错误栈，定位具体触发问题的代码行：

jekyll build --trace

根据详细日志可更精准定位依赖冲突点。

5. 验证页面Front Matter格式 #

确保index.md的Front Matter语法规范，使用三个短横线包裹，无YAML语法错误：

---
layout: home
title: TAU0005
nav_order: 1
---

内容的提问来源于stack exchange，提问作者Pedro Palazzo