Jekyll 3.7.2 发布解读Front Matter Defaults 与 collections_dir 回归修复实战指南【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyllJekyll 3.7.2发布于 2018-01-25是紧随 3.7.0 之后的一次关键补丁版本核心使命是修复 3.7.0 引入的两处回归Front Matter Defaults 路径扫描的性能退化以及自定义 collections_dir 导致根目录文章 URL 404。本文以该发布公告为骨架结合当前仓库源码深入讲解这两处缺陷的成因、修复原理与升级后的正确配置姿势同时给出 Windows 下监听性能优化建议帮助你在升级后避免踩坑、正确迁移目录结构。版本细节3.7.2 跳过了 3.7.1该编号因 RubyGems 发布流程问题被放弃本次发布修复了大量问题并同步更新了文档。一、背景3.7.0 引入了哪些新能力要理解 3.7.2 修复的回归需要先回顾 3.7.0 带来的两个新特性它们也正是本次回归的温床Front Matter Defaults 支持 Glob 通配模式允许在scope.path中使用包含*的模式如section/*/special-page.html来匹配默认值作用域详见 front-matter-defaults.md。自定义 collections 目录collections_dir允许把_posts、_drafts及所有自定义集合统一收纳到指定目录下详见 collections.md。二、回归一Front Matter Defaults 的性能退化与修复2.1 问题现象3.7.0 中当用户配置的scope[path]指向某个目录非通配符模式时Jekyll 会对该目录下的所有子文件夹与文件执行一次全量扫描Dir.glob并且对落在该 path 内的每一个文档都会重复执行。这在功能层面符合预期默认值确实应用到了该目录下的所有文件但代价是构建时间随目录规模线性恶化——目录越大、文件越多扫描开销越明显。2.2 修复方案仅通配模式才走 Glob3.7.2 的修复思路很直接只有当用户显式在scope[path]中使用通配符*时才执行目录 Glob 扫描普通目录路径直接走前缀匹配即可。从当前仓库源码可以清晰看到这一分支逻辑见 frontmatter_defaults.rbdef applies_path?(scope, path) rel_scope_path scope[path] return true if !rel_scope_path.is_a?(String) || rel_scope_path.empty? sanitized_path sanitize_path(path) if rel_scope_path.include?(*) glob_scope(sanitized_path, rel_scope_path) # 仅含 * 时触发 Dir.glob else path_is_subpath?(sanitized_path, strip_collections_dir(rel_scope_path)) # 否则纯前缀判断 end end关键点在于rel_scope_path.include?(*)这一判断普通目录路径不再触发Dir.glob从根本上消除了重复目录扫描的性能开销。而glob_scope内部还会通过glob_cache对同一个 glob 模式做缓存见 frontmatter_defaults.rb进一步避免重复扫描。2.3 对应测试仓库测试 test_front_matter_defaults.rb 中专门有两组用例shouldnotcallDir.globblock验证普通非通配scope 路径不会触发 Globshould callDir.globblock验证含通配符的 scope 路径按预期触发 Glob。一正一反两个用例锁死了该回归防止后续版本再次退化。2.4 升级后的配置建议如果你需要为某个目录批量设置默认值优先使用普通目录路径性能最佳defaults: - scope: path: projects # 普通目录3.7.2 后走纯前缀匹配无 Glob 开销 type: pages values: layout: project只有确实需要匹配任意子目录层级时才使用通配模式并清楚其性能代价官方文档在 front-matter-defaults.md 中明确警告glob 模式会随关联目录规模线性增加构建时间且目前尚未优化Windows 上尤其明显defaults: - scope: path: section/*/special-page.html # 含 * 的通配模式仅此场景走 Glob values: layout: specific-layout三、回归二collections_dir 导致根目录文章 4043.1 问题现象3.7.0 引入自定义 collections 目录后出现了一个隐蔽回归用户一旦设置了collection_dir实为配置键collections_dir仍留在站点源目录根部的 posts 会获得被改写的路径生成的文章 URL 与预期不符访问时表现为 404。3.2 修复方案自定义 collections_dir 后忽略根目录的 posts/drafts3.7.2 的决策是当用户自定义了collections_dir时Jekyll 将不再读取站点源目录根部的 posts 与 drafts——即要么全部收进自定义目录要么不要自定义。这一逻辑落地在 reader.rb 的retrieve_posts与outside_configured_directory?见 reader.rbdef retrieve_posts(dir) return if outside_configured_directory?(dir) site.posts.docs.concat(post_reader.read_posts(dir)) site.posts.docs.concat(post_reader.read_drafts(dir)) if site.show_drafts end def outside_configured_directory?(dir) collections_dir site.config[collections_dir] !collections_dir.empty? !dir.start_with?(/#{collections_dir}) end也就是说只要配置了非空的collections_dir所有不在/collections_dir前缀下的目录包括根目录都不会再被当作 posts/drafts 来源。3.3 迁移步骤把 posts 和 drafts 一起搬进去发布公告给出的迁移指引现已写入官方文档见 collections.md 中的警示框Be sure to move drafts and posts into custom collections directory在_config.yml中设置自定义目录collections_dir: my_collections将_posts与_drafts一并移入该目录my_collections/_posts my_collections/_drafts同时把你自定义的所有集合也放入该目录例如my_collections/_books、my_collections/_recipes。注意集合目录名不能以下划线_开头。迁移完成后{% post_url %}与{% link %}标签生成的链接会自动适配新路径无需手工修改——这一点由标签实现保证post_url.rb在解析时会把_posts前缀归一化见 post_url.rb而include.rb对页面路径会拼接collections_dir见 include.rb。同时front matter defaults 的路径匹配也会通过strip_collections_dir剥离collections_dir前缀后再做比较见 frontmatter_defaults.rb确保默认值配置依然按站点根相对路径语义工作。四、顺带优化Windows 下推荐安装 wdm3.7.2 还确认了一个开发体验改进在 Windows 上监听目录变化时gem wdm能显著提升jekyll serve的自动重建性能。官方因此建议在 Gemfile 中加入gem wdm, 0.1.0 if Gem.win_platform?建议按官方做法用Gem.win_platform?条件包裹避免影响非 Windows 平台。从 3.7.2 起jekyll new生成的新站点 Gemfile 会自动包含该 gem对应变更见 History.markdown 中的 Add gem wdm to all newly generated Gemfiles。五、本次发布的其他变更一览除上述两大修复外3.7.2 还包含若干次要修复与文档更新完整清单见 History.markdownBug Fixessafe 模式下明确提示不允许符号链接修复不同 Ruby 版本间的时区不一致重构collections_dir特性以保证一致性。Development FixesCI 增加 Ruby 2.5.0 测试新增 RuboCop 规则禁止向 master 提交#p/#puts调用等。Documentation补充collections_dir背景下 posts 的处理说明、collections_dir命名规范等。本次发布由 Alexandr、Andreas Möller、Ashwin Maroli、Chayoung You、Florian Thomas、Frank Taillandier、Hendrik Schneider、Kacper Duras、Olivia、Parker Moore、Paul Robert Lloyd 等贡献者共同完成。六、升级核对清单升级到 3.7.2或更高版本后建议按以下清单核对检查_config.yml中的defaults将可用普通目录路径替代的通配模式改回普通路径获得最佳构建性能若使用collections_dir确认_posts、_drafts及所有自定义集合都已移入该目录否则根目录下的文章将不再被读取核对文章 URL迁移后用{% post_url %}/{% link %}生成的链接应自动指向新位置抽查_site输出确认无 404Windows 用户确认 Gemfile 已加入wdm新站点默认自带旧站点需手动补充。完成以上核对后即可在修复性能回归与 URL 回归的基础上安心使用 3.7.0 引入的 Glob Defaults 与自定义集合目录两大新特性。【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Jekyll 3.7.2 发布解读：Front Matter Defaults 与 collections_dir 回归修复实战指南
Jekyll 3.7.2 发布解读Front Matter Defaults 与 collections_dir 回归修复实战指南【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyllJekyll 3.7.2发布于 2018-01-25是紧随 3.7.0 之后的一次关键补丁版本核心使命是修复 3.7.0 引入的两处回归Front Matter Defaults 路径扫描的性能退化以及自定义 collections_dir 导致根目录文章 URL 404。本文以该发布公告为骨架结合当前仓库源码深入讲解这两处缺陷的成因、修复原理与升级后的正确配置姿势同时给出 Windows 下监听性能优化建议帮助你在升级后避免踩坑、正确迁移目录结构。版本细节3.7.2 跳过了 3.7.1该编号因 RubyGems 发布流程问题被放弃本次发布修复了大量问题并同步更新了文档。一、背景3.7.0 引入了哪些新能力要理解 3.7.2 修复的回归需要先回顾 3.7.0 带来的两个新特性它们也正是本次回归的温床Front Matter Defaults 支持 Glob 通配模式允许在scope.path中使用包含*的模式如section/*/special-page.html来匹配默认值作用域详见 front-matter-defaults.md。自定义 collections 目录collections_dir允许把_posts、_drafts及所有自定义集合统一收纳到指定目录下详见 collections.md。二、回归一Front Matter Defaults 的性能退化与修复2.1 问题现象3.7.0 中当用户配置的scope[path]指向某个目录非通配符模式时Jekyll 会对该目录下的所有子文件夹与文件执行一次全量扫描Dir.glob并且对落在该 path 内的每一个文档都会重复执行。这在功能层面符合预期默认值确实应用到了该目录下的所有文件但代价是构建时间随目录规模线性恶化——目录越大、文件越多扫描开销越明显。2.2 修复方案仅通配模式才走 Glob3.7.2 的修复思路很直接只有当用户显式在scope[path]中使用通配符*时才执行目录 Glob 扫描普通目录路径直接走前缀匹配即可。从当前仓库源码可以清晰看到这一分支逻辑见 frontmatter_defaults.rbdef applies_path?(scope, path) rel_scope_path scope[path] return true if !rel_scope_path.is_a?(String) || rel_scope_path.empty? sanitized_path sanitize_path(path) if rel_scope_path.include?(*) glob_scope(sanitized_path, rel_scope_path) # 仅含 * 时触发 Dir.glob else path_is_subpath?(sanitized_path, strip_collections_dir(rel_scope_path)) # 否则纯前缀判断 end end关键点在于rel_scope_path.include?(*)这一判断普通目录路径不再触发Dir.glob从根本上消除了重复目录扫描的性能开销。而glob_scope内部还会通过glob_cache对同一个 glob 模式做缓存见 frontmatter_defaults.rb进一步避免重复扫描。2.3 对应测试仓库测试 test_front_matter_defaults.rb 中专门有两组用例shouldnotcallDir.globblock验证普通非通配scope 路径不会触发 Globshould callDir.globblock验证含通配符的 scope 路径按预期触发 Glob。一正一反两个用例锁死了该回归防止后续版本再次退化。2.4 升级后的配置建议如果你需要为某个目录批量设置默认值优先使用普通目录路径性能最佳defaults: - scope: path: projects # 普通目录3.7.2 后走纯前缀匹配无 Glob 开销 type: pages values: layout: project只有确实需要匹配任意子目录层级时才使用通配模式并清楚其性能代价官方文档在 front-matter-defaults.md 中明确警告glob 模式会随关联目录规模线性增加构建时间且目前尚未优化Windows 上尤其明显defaults: - scope: path: section/*/special-page.html # 含 * 的通配模式仅此场景走 Glob values: layout: specific-layout三、回归二collections_dir 导致根目录文章 4043.1 问题现象3.7.0 引入自定义 collections 目录后出现了一个隐蔽回归用户一旦设置了collection_dir实为配置键collections_dir仍留在站点源目录根部的 posts 会获得被改写的路径生成的文章 URL 与预期不符访问时表现为 404。3.2 修复方案自定义 collections_dir 后忽略根目录的 posts/drafts3.7.2 的决策是当用户自定义了collections_dir时Jekyll 将不再读取站点源目录根部的 posts 与 drafts——即要么全部收进自定义目录要么不要自定义。这一逻辑落地在 reader.rb 的retrieve_posts与outside_configured_directory?见 reader.rbdef retrieve_posts(dir) return if outside_configured_directory?(dir) site.posts.docs.concat(post_reader.read_posts(dir)) site.posts.docs.concat(post_reader.read_drafts(dir)) if site.show_drafts end def outside_configured_directory?(dir) collections_dir site.config[collections_dir] !collections_dir.empty? !dir.start_with?(/#{collections_dir}) end也就是说只要配置了非空的collections_dir所有不在/collections_dir前缀下的目录包括根目录都不会再被当作 posts/drafts 来源。3.3 迁移步骤把 posts 和 drafts 一起搬进去发布公告给出的迁移指引现已写入官方文档见 collections.md 中的警示框Be sure to move drafts and posts into custom collections directory在_config.yml中设置自定义目录collections_dir: my_collections将_posts与_drafts一并移入该目录my_collections/_posts my_collections/_drafts同时把你自定义的所有集合也放入该目录例如my_collections/_books、my_collections/_recipes。注意集合目录名不能以下划线_开头。迁移完成后{% post_url %}与{% link %}标签生成的链接会自动适配新路径无需手工修改——这一点由标签实现保证post_url.rb在解析时会把_posts前缀归一化见 post_url.rb而include.rb对页面路径会拼接collections_dir见 include.rb。同时front matter defaults 的路径匹配也会通过strip_collections_dir剥离collections_dir前缀后再做比较见 frontmatter_defaults.rb确保默认值配置依然按站点根相对路径语义工作。四、顺带优化Windows 下推荐安装 wdm3.7.2 还确认了一个开发体验改进在 Windows 上监听目录变化时gem wdm能显著提升jekyll serve的自动重建性能。官方因此建议在 Gemfile 中加入gem wdm, 0.1.0 if Gem.win_platform?建议按官方做法用Gem.win_platform?条件包裹避免影响非 Windows 平台。从 3.7.2 起jekyll new生成的新站点 Gemfile 会自动包含该 gem对应变更见 History.markdown 中的 Add gem wdm to all newly generated Gemfiles。五、本次发布的其他变更一览除上述两大修复外3.7.2 还包含若干次要修复与文档更新完整清单见 History.markdownBug Fixessafe 模式下明确提示不允许符号链接修复不同 Ruby 版本间的时区不一致重构collections_dir特性以保证一致性。Development FixesCI 增加 Ruby 2.5.0 测试新增 RuboCop 规则禁止向 master 提交#p/#puts调用等。Documentation补充collections_dir背景下 posts 的处理说明、collections_dir命名规范等。本次发布由 Alexandr、Andreas Möller、Ashwin Maroli、Chayoung You、Florian Thomas、Frank Taillandier、Hendrik Schneider、Kacper Duras、Olivia、Parker Moore、Paul Robert Lloyd 等贡献者共同完成。六、升级核对清单升级到 3.7.2或更高版本后建议按以下清单核对检查_config.yml中的defaults将可用普通目录路径替代的通配模式改回普通路径获得最佳构建性能若使用collections_dir确认_posts、_drafts及所有自定义集合都已移入该目录否则根目录下的文章将不再被读取核对文章 URL迁移后用{% post_url %}/{% link %}生成的链接应自动指向新位置抽查_site输出确认无 404Windows 用户确认 Gemfile 已加入wdm新站点默认自带旧站点需手动补充。完成以上核对后即可在修复性能回归与 URL 回归的基础上安心使用 3.7.0 引入的 Glob Defaults 与自定义集合目录两大新特性。【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考