Jekyll 2.5.2 发布路径净化回归修复与 post_url 标签匹配机制升级解析【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll本文围绕 Jekyll 2.5.2 补丁版的两项核心修复展开一是修复 2.5.1 引入的路径净化path sanitation回归缺陷二是将post_url标签的匹配逻辑从「编译时间 名称」升级为「按文章文件名精确匹配」以消除时区差异导致的日期错配问题。读者可借此掌握 Jekyll 路径安全机制的底层实现以及post_url标签的正确使用方式与演进脉络从而在升级或排查问题时有的放矢。发布背景紧随 2.5.1 的补丁版本Jekyll 2.5.2 于 2014 年 11 月 12 日发布作者为 parkr属于一次非常小型的维护发布。其发布说明docs/_posts/2014-11-12-jekyll-2-5-2-released.markdown只记载了两件事修复 2.5.1 引入的路径净化path sanitationbug改进post_url标签由原先「按编译时间与名称」匹配改为「按文章文件名例如2014-03-03-my-cool-post匹配」从而解决因时区差异导致文章创建日期「跨天」而产生的匹配失败问题。要理解这次修复的价值需要先回顾 2.5.1。2.5.1docs/_posts/2014-11-08-jekyll-2-5-1-released.markdown的主要工作是修复 2.5.0 中一个已确认在 Windows 上出现问题的路径净化变更。当时的发布说明特别提到核心团队没有 Windows 开发机为保障未来版本在 Windows 上的可用性社区成立了「Windows 测试小组」Windows Test Force专门在发布前验证 Windows 兼容性。因此 2.5.2 的「路径净化回归修复」正是 2.5.0 → 2.5.1 → 2.5.2 这条补丁链的收尾确保路径净化改动在主流平台含 Windows上都稳定可靠。修复一路径净化Path Sanitation回归什么是路径净化路径净化是 Jekyll 保证安全性的基础机制所有从用户输入如配置项、front matter、include 参数、URL 等获得的路径在拼接到站点的 source、destination、theme、cache 等目录之前都必须经过净化处理防止用户以../等方式越出基目录访问任意文件系统路径。在 lib/jekyll/path_manager.rb 中路径净化由Jekyll::PathManager.sanitized_path(base_directory, questionable_path)实现其核心逻辑为当questionable_path为nil时直接返回冻结的基目录字符串以~开头的路径会被插入/前缀再交由File.expand_path处理规避不同平台对家目录展开的差异调用File.expand_path规范化路径若结果与基目录相同则直接返回使用squeeze!(/)清理多余的连续斜杠并剥离 Windows 风格的盘符前缀\A\w:/最终通过PathManager.join将净化结果拼回基目录并返回冻结frozen字符串防止调用方无意篡改缓存值。该实现还带有一个典型的性能考量File.join每次调用都会新分配数组与字符串而PathManager通过join、sanitized_path等缓存表对相同参数的调用结果做缓存注意注释中说明缓存永不清理以支持站点增量再生成并冻结结果以避免缓存被意外修改。回归问题与修复的印证在 lib/jekyll.rb 中Jekyll.sanitized_path是PathManager.sanitized_path的全局快捷入口被广泛调用。以 lib/jekyll/site.rb 为例in_source_dir、in_theme_dir、in_dest_dir、in_cache_dir四个方法都通过reduce将路径逐段交给Jekyll.sanitized_path净化此外 lib/jekyll/configuration.rb 在探测_config文件时也使用净化后的路径。也就是说路径净化一旦出现回归会波及站点源码读取、主题加载、构建输出与缓存目录等多个核心环节。而 2.5.0/2.5.1 时代引入的路径净化改动在 Windows 上有平台相关的坑例如盘符、反斜杠、绝对路径前缀的判定差异这正是 2.5.1 需要紧急修复、2.5.2 又继续打补丁的原因。当前仓库中的测试 test/test_path_manager.rb 印证了修复后的行为边界传入nil时返回基目录本身的冻结副本传入能展开为基目录的路径如File.join(source, /)时同样返回冻结的基目录在 Windows 平台上E:\_config.yml这类带盘符的输入会被正确净化为source/_config.yml//_config.yml这类多重前导斜杠输入同样会被正确规范化并返回冻结结果。从当前源码看该机制在后续演进中已相当稳健2.5.2 所修复的回归在今天已沉淀为「路径必须先净化、再拼接」的稳定约定。读者若关心 Windows 兼容细节可结合 lib/jekyll/utils/platforms.rb 中平台检测逻辑一起阅读。修复二post_url 标签改为按文件名精确匹配旧实现的问题时间与名称的组合匹配post_url是 Jekyll 内置 Liquid 标签用于在模板中生成指向指定文章的 permalink。2.5.2 之前其匹配方式为「编译后得到的日期时间 名称slug」的组合比较系统先把文章文件名解析出日期与 slug再与目标文章对象的date字段编译时的时间对象和 slug 进行比较。这种做法的隐患在于文章文件名中的日期如2014-03-03与文件系统创建/编译时间并不总是同一天。当站点构建所在时区与文章时间戳所在时区不一致时Time对象在不同时区下可能被格式化出不同的本地日期导致「文件名写着 3 月 3 日编译时间算出来却是 3 月 2 日」的错配post_url因而找不到文章或匹配到错误文章。新实现按文件名path-date-slug精确匹配2.5.2 将匹配逻辑改为直接以文章文件名为基准。当前仓库中 lib/jekyll/tags/post_url.rb 的实现体现了这一设计的最终形态解析阶段PostComparer用正则POST_PATH_MATCHER %r!\A(./)*?(\d{2,4}-\d{1,2}-\d{1,2})-([^/]*)\z!从标签参数中提取三部分可选子目录路径、日期YYYY-M-D允许 2~4 位年份、slug随后构造name_regex %r!\A_posts/#{path}#{basename_pattern}|\A#{path}_posts/?#{basename_pattern}!其中basename_pattern为「日期-slug.任意扩展名」匹配阶段PostUrl#render遍历site.posts.docs当某篇文章的relative_path能匹配该正则时即命中返回relative_url(post)若第一轮未命中则回退到旧的「slug 编译时间年月日」匹配deprecated_equality命中时会输出弃用警告log_legacy_usage_deprecation提示用户将标签参数改为与文章文件名完全一致——这正是「按文件名匹配」迁移期的兼容性设计两种方式均未命中时抛出Jekyll::Errors::PostURLError提示文章不存在或名称不合法raise_post_not_found_error。这里要特别说明发布说明中「checks the posts name instead of a compiled time and name」指的是 2.5.2 引入了「按文件名name匹配」这一修复方向即忽略编译时的时间对象、不再受时区与「跨天」影响而当前源码中第一轮正则匹配与第二轮兼容性回退deprecated_equality注释明确标注将在 v5.0 移除的分层结构是这一设计在后续版本中进一步强化的结果。测试用例如何验证test/test_tag_post_url.rb 从多个维度验证了该标签基础用例{% post_url 2008-11-21-complex %}正确渲染为/2008/11/21/complex/特殊字符2016-11-26-special-chars-()渲染为/2016/11/26/special-chars-\(\\)/保证括号等字符不被误解析嵌套目录/2008-11-21-complex、es/2008-11-21-nested等带路径含前导斜杠的形式均能正确命中弃用路径在不写子目录前缀而文章实际位于子目录时标签仍能通过旧逻辑命中但会输出弃用警告消息非法输入abc2008-11-21-complex抛出PostURLError2008-42-21-complex非法月份 42抛出InvalidDateError。这些用例表明2.5.2 的修复让post_url的匹配行为完全由「文章文件名」这一确定性的来源驱动不依赖运行时时间对象从而从根本上消除了时区「跨天」类问题同时保留了向后兼容的降级路径。附录post_url 标签的正确用法结合官方文档 docs/_docs/liquid/tags.md 的「Linking to posts」一节给出与 2.5.2 匹配逻辑一致的实战用法基本用法无需扩展名Jekyll 自动解析日期与 slug{% post_url 2010-07-21-name-of-post %}文章位于_posts子目录时须带子目录路径{% post_url /subdir/2010-07-21-name-of-post %}在 Markdown 中构造链接文章标题自 Jekyll 4.0 起无需再为link、post_url手动拼site.baseurl结合数据文件如_data/cool_posts.yaml循环输出时可使用{% post_url {{ cool_post.slug }} %}形式。使用提示由于 2.5.2 起匹配基准是「文件名」请务必保证标签参数与文章文件名含子目录、日期、slug完全一致若遇到命中旧逻辑并出现弃用警告说明参数与文件名不完全匹配应按警告提示修正。小结Jekyll 2.5.2 虽是一次「非常小型」的发布却踩准了两个关键点其一完成 2.5.0 以来路径净化改动的跨平台收尾今天源码中的PathManager冻结字符串缓存、Windows 盘符剥离等细节都是这条修复链的沉淀其二将post_url从「编译时间 名称」的脆弱匹配升级为「文件名精确匹配」从机制上消灭了时区导致的日期错配并在后续版本中演化为「严格匹配优先、旧逻辑降级兼容并告警」的双层结构。对使用者而言理解这两处修复也就理解了 Jekyll 在路径安全与链接生成两条主线上的一贯设计原则。【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Jekyll 2.5.2 发布：路径净化回归修复与 post_url 标签匹配机制升级解析
Jekyll 2.5.2 发布路径净化回归修复与 post_url 标签匹配机制升级解析【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll本文围绕 Jekyll 2.5.2 补丁版的两项核心修复展开一是修复 2.5.1 引入的路径净化path sanitation回归缺陷二是将post_url标签的匹配逻辑从「编译时间 名称」升级为「按文章文件名精确匹配」以消除时区差异导致的日期错配问题。读者可借此掌握 Jekyll 路径安全机制的底层实现以及post_url标签的正确使用方式与演进脉络从而在升级或排查问题时有的放矢。发布背景紧随 2.5.1 的补丁版本Jekyll 2.5.2 于 2014 年 11 月 12 日发布作者为 parkr属于一次非常小型的维护发布。其发布说明docs/_posts/2014-11-12-jekyll-2-5-2-released.markdown只记载了两件事修复 2.5.1 引入的路径净化path sanitationbug改进post_url标签由原先「按编译时间与名称」匹配改为「按文章文件名例如2014-03-03-my-cool-post匹配」从而解决因时区差异导致文章创建日期「跨天」而产生的匹配失败问题。要理解这次修复的价值需要先回顾 2.5.1。2.5.1docs/_posts/2014-11-08-jekyll-2-5-1-released.markdown的主要工作是修复 2.5.0 中一个已确认在 Windows 上出现问题的路径净化变更。当时的发布说明特别提到核心团队没有 Windows 开发机为保障未来版本在 Windows 上的可用性社区成立了「Windows 测试小组」Windows Test Force专门在发布前验证 Windows 兼容性。因此 2.5.2 的「路径净化回归修复」正是 2.5.0 → 2.5.1 → 2.5.2 这条补丁链的收尾确保路径净化改动在主流平台含 Windows上都稳定可靠。修复一路径净化Path Sanitation回归什么是路径净化路径净化是 Jekyll 保证安全性的基础机制所有从用户输入如配置项、front matter、include 参数、URL 等获得的路径在拼接到站点的 source、destination、theme、cache 等目录之前都必须经过净化处理防止用户以../等方式越出基目录访问任意文件系统路径。在 lib/jekyll/path_manager.rb 中路径净化由Jekyll::PathManager.sanitized_path(base_directory, questionable_path)实现其核心逻辑为当questionable_path为nil时直接返回冻结的基目录字符串以~开头的路径会被插入/前缀再交由File.expand_path处理规避不同平台对家目录展开的差异调用File.expand_path规范化路径若结果与基目录相同则直接返回使用squeeze!(/)清理多余的连续斜杠并剥离 Windows 风格的盘符前缀\A\w:/最终通过PathManager.join将净化结果拼回基目录并返回冻结frozen字符串防止调用方无意篡改缓存值。该实现还带有一个典型的性能考量File.join每次调用都会新分配数组与字符串而PathManager通过join、sanitized_path等缓存表对相同参数的调用结果做缓存注意注释中说明缓存永不清理以支持站点增量再生成并冻结结果以避免缓存被意外修改。回归问题与修复的印证在 lib/jekyll.rb 中Jekyll.sanitized_path是PathManager.sanitized_path的全局快捷入口被广泛调用。以 lib/jekyll/site.rb 为例in_source_dir、in_theme_dir、in_dest_dir、in_cache_dir四个方法都通过reduce将路径逐段交给Jekyll.sanitized_path净化此外 lib/jekyll/configuration.rb 在探测_config文件时也使用净化后的路径。也就是说路径净化一旦出现回归会波及站点源码读取、主题加载、构建输出与缓存目录等多个核心环节。而 2.5.0/2.5.1 时代引入的路径净化改动在 Windows 上有平台相关的坑例如盘符、反斜杠、绝对路径前缀的判定差异这正是 2.5.1 需要紧急修复、2.5.2 又继续打补丁的原因。当前仓库中的测试 test/test_path_manager.rb 印证了修复后的行为边界传入nil时返回基目录本身的冻结副本传入能展开为基目录的路径如File.join(source, /)时同样返回冻结的基目录在 Windows 平台上E:\_config.yml这类带盘符的输入会被正确净化为source/_config.yml//_config.yml这类多重前导斜杠输入同样会被正确规范化并返回冻结结果。从当前源码看该机制在后续演进中已相当稳健2.5.2 所修复的回归在今天已沉淀为「路径必须先净化、再拼接」的稳定约定。读者若关心 Windows 兼容细节可结合 lib/jekyll/utils/platforms.rb 中平台检测逻辑一起阅读。修复二post_url 标签改为按文件名精确匹配旧实现的问题时间与名称的组合匹配post_url是 Jekyll 内置 Liquid 标签用于在模板中生成指向指定文章的 permalink。2.5.2 之前其匹配方式为「编译后得到的日期时间 名称slug」的组合比较系统先把文章文件名解析出日期与 slug再与目标文章对象的date字段编译时的时间对象和 slug 进行比较。这种做法的隐患在于文章文件名中的日期如2014-03-03与文件系统创建/编译时间并不总是同一天。当站点构建所在时区与文章时间戳所在时区不一致时Time对象在不同时区下可能被格式化出不同的本地日期导致「文件名写着 3 月 3 日编译时间算出来却是 3 月 2 日」的错配post_url因而找不到文章或匹配到错误文章。新实现按文件名path-date-slug精确匹配2.5.2 将匹配逻辑改为直接以文章文件名为基准。当前仓库中 lib/jekyll/tags/post_url.rb 的实现体现了这一设计的最终形态解析阶段PostComparer用正则POST_PATH_MATCHER %r!\A(./)*?(\d{2,4}-\d{1,2}-\d{1,2})-([^/]*)\z!从标签参数中提取三部分可选子目录路径、日期YYYY-M-D允许 2~4 位年份、slug随后构造name_regex %r!\A_posts/#{path}#{basename_pattern}|\A#{path}_posts/?#{basename_pattern}!其中basename_pattern为「日期-slug.任意扩展名」匹配阶段PostUrl#render遍历site.posts.docs当某篇文章的relative_path能匹配该正则时即命中返回relative_url(post)若第一轮未命中则回退到旧的「slug 编译时间年月日」匹配deprecated_equality命中时会输出弃用警告log_legacy_usage_deprecation提示用户将标签参数改为与文章文件名完全一致——这正是「按文件名匹配」迁移期的兼容性设计两种方式均未命中时抛出Jekyll::Errors::PostURLError提示文章不存在或名称不合法raise_post_not_found_error。这里要特别说明发布说明中「checks the posts name instead of a compiled time and name」指的是 2.5.2 引入了「按文件名name匹配」这一修复方向即忽略编译时的时间对象、不再受时区与「跨天」影响而当前源码中第一轮正则匹配与第二轮兼容性回退deprecated_equality注释明确标注将在 v5.0 移除的分层结构是这一设计在后续版本中进一步强化的结果。测试用例如何验证test/test_tag_post_url.rb 从多个维度验证了该标签基础用例{% post_url 2008-11-21-complex %}正确渲染为/2008/11/21/complex/特殊字符2016-11-26-special-chars-()渲染为/2016/11/26/special-chars-\(\\)/保证括号等字符不被误解析嵌套目录/2008-11-21-complex、es/2008-11-21-nested等带路径含前导斜杠的形式均能正确命中弃用路径在不写子目录前缀而文章实际位于子目录时标签仍能通过旧逻辑命中但会输出弃用警告消息非法输入abc2008-11-21-complex抛出PostURLError2008-42-21-complex非法月份 42抛出InvalidDateError。这些用例表明2.5.2 的修复让post_url的匹配行为完全由「文章文件名」这一确定性的来源驱动不依赖运行时时间对象从而从根本上消除了时区「跨天」类问题同时保留了向后兼容的降级路径。附录post_url 标签的正确用法结合官方文档 docs/_docs/liquid/tags.md 的「Linking to posts」一节给出与 2.5.2 匹配逻辑一致的实战用法基本用法无需扩展名Jekyll 自动解析日期与 slug{% post_url 2010-07-21-name-of-post %}文章位于_posts子目录时须带子目录路径{% post_url /subdir/2010-07-21-name-of-post %}在 Markdown 中构造链接文章标题自 Jekyll 4.0 起无需再为link、post_url手动拼site.baseurl结合数据文件如_data/cool_posts.yaml循环输出时可使用{% post_url {{ cool_post.slug }} %}形式。使用提示由于 2.5.2 起匹配基准是「文件名」请务必保证标签参数与文章文件名含子目录、日期、slug完全一致若遇到命中旧逻辑并出现弃用警告说明参数与文件名不完全匹配应按警告提示修正。小结Jekyll 2.5.2 虽是一次「非常小型」的发布却踩准了两个关键点其一完成 2.5.0 以来路径净化改动的跨平台收尾今天源码中的PathManager冻结字符串缓存、Windows 盘符剥离等细节都是这条修复链的沉淀其二将post_url从「编译时间 名称」的脆弱匹配升级为「文件名精确匹配」从机制上消灭了时区导致的日期错配并在后续版本中演化为「严格匹配优先、旧逻辑降级兼容并告警」的双层结构。对使用者而言理解这两处修复也就理解了 Jekyll 在路径安全与链接生成两条主线上的一贯设计原则。【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考