Jekyll 4.2.1 发布解读site.url 行为回退、可变属性渲染修复与增量再生成问题【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyllJekyll 4.2.1 是 2021 年 9 月 27 日发布的小版本集中修复了 v4.2.0 引入的两处回归site.url不再被 localhost 覆盖所引发的绝对链接指向未部署资源、Liquid 渲染优化导致{{ page.content }}等可变属性失效并顺带修复了一个从 Jekyll 3 时代遗留下来的、与自定义collections_dir相关的增量再生 bug。本文基于仓库中的发布说明、History.markdown 变更记录以及对应源码实现逐项拆解这三个修复的来龙去脉、底层原理与升级后的验证方式帮助你在升级到 4.2.x 分支后避免踩同样的坑。版本背景一次发布修复三个问题v4.2.1 发布公告明确说明该版本包含两类改动修复 v4.2.0 引入的两个回归修复一个继承自 Jekyll 3 的老 bug。对应到 History.markdown 中的 Bug Fixes 条目即回退 #7253Dont resetsite.urlto localhost:4000 by defaultPR #8808backport #8620修复 Convertible 模块回归v4.2.0 对页面与布局的 Liquid 表示生成做了优化导致可变属性无法反映最新状态PR #8793backport #8786尊重collections_dir配置在include标签及增量再生流程中正确处理自定义集合目录PR #8794backport #8756。下面分别展开。修复一回退不再覆盖 site.url的决定问题的起因在 v4.2.0 之前运行jekyll serve默认 development 模式时Jekyll 会把配置中的site.url临时覆盖为本地地址如http://localhost:4000。v4.2.0PR #7253决定停止这种覆盖理由是避免用户为了生成生产构建而不得不额外执行一次jekyll build。引发的回归这个决定的初衷是好的却带来了一个未预料到的后果当开发模式下的site.url不再被覆盖时站点中的绝对 URL例如通过{{ site.url }}{{ page.url }}或相关过滤器生成的链接会直接指向_config.yml中配置的正式域名。而该域名上的资源往往尚未部署于是本地开发流程中点击链接就会 404——本地预览与线上资源状态脱节开发者工作流被破坏。4.2.1 的回退方案4.2.1 采纳了 benik 的提议回退这一改动。从当前仓库源码可以看到该行为被长期保留在 lib/jekyll/commands/serve.rb 中jekyll serve的动作在 development 环境下会执行config[url] default_url(config) if Jekyll.env development而default_urllib/jekyll/commands/serve.rb会根据host与port拼出本地地址def default_url(opts) config configuration_from_options(opts) format_url( config[ssl_cert] config[ssl_key], config[host] 127.0.0.1 ? localhost : config[host], config[port] ) end也就是说只要你是用jekyll serve在本地开发development 环境site.url就会被临时指向本地服务器地址绝对链接得以在本地正常访问而当你显式运行jekyll buildproduction 构建时site.url保持为配置中的正式值。这正好平衡了两类工作流本地预览不再出现指向未部署资源的绝对链接同时生产构建也无需额外设置。经验法则本地预览用jekyll serve发布前用jekyll build产出以正式site.url为基准的静态文件二者互不干扰。修复二Liquid 渲染优化回归与可变属性失效回归的根源v4.2.0 引入了一系列围绕站点独立页面pages与布局layouts的 Liquid 表示生成的优化见 History.markdown 中大量 Reduce allocations、Stash attribute hash for Liquid computed for pages 等条目。优化本身旨在减少渲染过程中的内存分配、提升性能但副作用是{{ page.content }}等可变属性不再反映请求时的最新状态导致所有依赖这些可变属性的资源渲染结果出错。可变属性的原理在 Jekyll 的 Drop 体系中page、document等对象经由to_liquid转换为 Drop 后暴露给 Liquid 模板。Drop 的取属性逻辑在 lib/jekyll/drops/drop.rb 中若 Drop 是mutable可变的取值时优先返回mutations运行时被改写的值若不可变则只能委托给底层对象的方法。以文档为例lib/jekyll/drops/document_drop.rb 中NESTED_OBJECT_FIELD_BLACKLIST %w( content output excerpt next previous ).freeze mutable false delegate_methods :id, :output, :content, :to_s, :relative_path, :url, :datecontent、output等字段通过delegate_methods委托给文档对象实时读取。当 v4.2.0 的优化提前缓存了页面/布局的 Liquid 属性哈希后这些委托方法的实时性被破坏——模板中读取到的content是缓存快照而不是当前渲染阶段的最新值。Liquid 模板在 lib/jekyll/liquid_renderer/file.rb 中被解析并缓存renderer.cache[filename] || Liquid::Template.parse(...)渲染时通过reset_template_assigns清理实例赋值这一缓存机制与属性快照问题叠加放大了回归的影响。修复方式4.2.1 回退/修正了 Convertible 模块中的相关改动PR #8793恢复可变属性的实时读取语义。pdmosses 为此提供了复现用测试仓库帮助团队定位问题。这一案例也说明渲染优化不能以牺牲模板变量的动态语义为代价。修复三自定义 collections_dir 下的增量再生问题表现第三个修复针对的是增量再生incremental regeneration当站点通过collections_dir为所有集合配置了自定义目录时增量模式下对集合内文档的修改被忽略不会触发重新生成。这个问题并非 v4.2.0 引入而是继承自 Jekyll 3 的老 bug。相关实现增量再生由 lib/jekyll/regenerator.rb 负责它把已处理文件的mtime与依赖列表持久化到.jekyll-metadatametadata_file指向site.in_source_dir(.jekyll-metadata)见 regenerator.rb后续构建时通过比较 mtime 决定是否重新生成existing_file_modified?见 regenerator.rb。而collections_dir的默认值为空字符串lib/jekyll/configuration.rb集合容器路径取site.config[collections_dir]lib/jekyll/collection.rb。当配置了自定义collections_dir时集合文档、静态文件以及include标签解析所涉及的路径都需要拼接该前缀例如 lib/jekyll/static_file.rb、lib/jekyll/tags/include.rb。4.2.1 的修复正是让include标签及相关路径解析尊重collections_dir配置PR #8756从而保证增量模式下能正确感知集合内文档的变更。增量模式的启用方式CLIjekyll build --incremental/jekyll serve --incremental-I简写见 lib/jekyll/command.rb配置_config.yml中设置incremental: true默认false见 lib/jekyll/configuration.rb。该流程的端到端行为在 features/incremental_rebuild.feature 中由 Cucumber 场景覆盖单元层面的 mtime/依赖判断逻辑见 test/test_regenerator.rb。如何验证你已正确升级确认版本号jekyll --version应输出4.2.1或更高也可直接查看 lib/jekyll/version.rb 确认仓库当前版本。验证 site.url 行为在 development 环境下运行jekyll serve在模板中输出{{ site.url }}应显示本地服务器地址运行jekyll build后输出应为_config.yml中的正式值。验证可变属性在页面模板中使用{{ page.content }}或依赖content的布局如 docs/_layouts/default.html渲染确认输出与页面实际内容一致。验证增量再生配置collections_dir后以--incremental模式启动修改集合内某篇文档确认对应输出被重新生成且.jekyll-metadata中的 mtime 记录同步更新。小结Jekyll 4.2.1 虽然是小版本却是一次典型的回归修复范本既有对 v4.2.0 激进改动的理性回退site.url覆盖、Liquid 可变属性也有对历史债务的补课collections_dir增量再生。三个修复共同保障了jekyll serve本地开发与jekyll build生产构建两条工作流的稳定衔接。对使用 4.2.0 的用户而言升级到 4.2.1或当前仓库所代表的 4.4.x 系列即可同时消除绝对链接失效与可变属性渲染异常对插件与主题开发者而言理解 Drop 的可变属性语义lib/jekyll/drops/drop.rb和增量再生依赖机制lib/jekyll/regenerator.rb能帮助你在后续版本中规避同类问题。【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Jekyll 4.2.1 发布解读：site.url 行为回退、可变属性渲染修复与增量再生成问题
Jekyll 4.2.1 发布解读site.url 行为回退、可变属性渲染修复与增量再生成问题【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyllJekyll 4.2.1 是 2021 年 9 月 27 日发布的小版本集中修复了 v4.2.0 引入的两处回归site.url不再被 localhost 覆盖所引发的绝对链接指向未部署资源、Liquid 渲染优化导致{{ page.content }}等可变属性失效并顺带修复了一个从 Jekyll 3 时代遗留下来的、与自定义collections_dir相关的增量再生 bug。本文基于仓库中的发布说明、History.markdown 变更记录以及对应源码实现逐项拆解这三个修复的来龙去脉、底层原理与升级后的验证方式帮助你在升级到 4.2.x 分支后避免踩同样的坑。版本背景一次发布修复三个问题v4.2.1 发布公告明确说明该版本包含两类改动修复 v4.2.0 引入的两个回归修复一个继承自 Jekyll 3 的老 bug。对应到 History.markdown 中的 Bug Fixes 条目即回退 #7253Dont resetsite.urlto localhost:4000 by defaultPR #8808backport #8620修复 Convertible 模块回归v4.2.0 对页面与布局的 Liquid 表示生成做了优化导致可变属性无法反映最新状态PR #8793backport #8786尊重collections_dir配置在include标签及增量再生流程中正确处理自定义集合目录PR #8794backport #8756。下面分别展开。修复一回退不再覆盖 site.url的决定问题的起因在 v4.2.0 之前运行jekyll serve默认 development 模式时Jekyll 会把配置中的site.url临时覆盖为本地地址如http://localhost:4000。v4.2.0PR #7253决定停止这种覆盖理由是避免用户为了生成生产构建而不得不额外执行一次jekyll build。引发的回归这个决定的初衷是好的却带来了一个未预料到的后果当开发模式下的site.url不再被覆盖时站点中的绝对 URL例如通过{{ site.url }}{{ page.url }}或相关过滤器生成的链接会直接指向_config.yml中配置的正式域名。而该域名上的资源往往尚未部署于是本地开发流程中点击链接就会 404——本地预览与线上资源状态脱节开发者工作流被破坏。4.2.1 的回退方案4.2.1 采纳了 benik 的提议回退这一改动。从当前仓库源码可以看到该行为被长期保留在 lib/jekyll/commands/serve.rb 中jekyll serve的动作在 development 环境下会执行config[url] default_url(config) if Jekyll.env development而default_urllib/jekyll/commands/serve.rb会根据host与port拼出本地地址def default_url(opts) config configuration_from_options(opts) format_url( config[ssl_cert] config[ssl_key], config[host] 127.0.0.1 ? localhost : config[host], config[port] ) end也就是说只要你是用jekyll serve在本地开发development 环境site.url就会被临时指向本地服务器地址绝对链接得以在本地正常访问而当你显式运行jekyll buildproduction 构建时site.url保持为配置中的正式值。这正好平衡了两类工作流本地预览不再出现指向未部署资源的绝对链接同时生产构建也无需额外设置。经验法则本地预览用jekyll serve发布前用jekyll build产出以正式site.url为基准的静态文件二者互不干扰。修复二Liquid 渲染优化回归与可变属性失效回归的根源v4.2.0 引入了一系列围绕站点独立页面pages与布局layouts的 Liquid 表示生成的优化见 History.markdown 中大量 Reduce allocations、Stash attribute hash for Liquid computed for pages 等条目。优化本身旨在减少渲染过程中的内存分配、提升性能但副作用是{{ page.content }}等可变属性不再反映请求时的最新状态导致所有依赖这些可变属性的资源渲染结果出错。可变属性的原理在 Jekyll 的 Drop 体系中page、document等对象经由to_liquid转换为 Drop 后暴露给 Liquid 模板。Drop 的取属性逻辑在 lib/jekyll/drops/drop.rb 中若 Drop 是mutable可变的取值时优先返回mutations运行时被改写的值若不可变则只能委托给底层对象的方法。以文档为例lib/jekyll/drops/document_drop.rb 中NESTED_OBJECT_FIELD_BLACKLIST %w( content output excerpt next previous ).freeze mutable false delegate_methods :id, :output, :content, :to_s, :relative_path, :url, :datecontent、output等字段通过delegate_methods委托给文档对象实时读取。当 v4.2.0 的优化提前缓存了页面/布局的 Liquid 属性哈希后这些委托方法的实时性被破坏——模板中读取到的content是缓存快照而不是当前渲染阶段的最新值。Liquid 模板在 lib/jekyll/liquid_renderer/file.rb 中被解析并缓存renderer.cache[filename] || Liquid::Template.parse(...)渲染时通过reset_template_assigns清理实例赋值这一缓存机制与属性快照问题叠加放大了回归的影响。修复方式4.2.1 回退/修正了 Convertible 模块中的相关改动PR #8793恢复可变属性的实时读取语义。pdmosses 为此提供了复现用测试仓库帮助团队定位问题。这一案例也说明渲染优化不能以牺牲模板变量的动态语义为代价。修复三自定义 collections_dir 下的增量再生问题表现第三个修复针对的是增量再生incremental regeneration当站点通过collections_dir为所有集合配置了自定义目录时增量模式下对集合内文档的修改被忽略不会触发重新生成。这个问题并非 v4.2.0 引入而是继承自 Jekyll 3 的老 bug。相关实现增量再生由 lib/jekyll/regenerator.rb 负责它把已处理文件的mtime与依赖列表持久化到.jekyll-metadatametadata_file指向site.in_source_dir(.jekyll-metadata)见 regenerator.rb后续构建时通过比较 mtime 决定是否重新生成existing_file_modified?见 regenerator.rb。而collections_dir的默认值为空字符串lib/jekyll/configuration.rb集合容器路径取site.config[collections_dir]lib/jekyll/collection.rb。当配置了自定义collections_dir时集合文档、静态文件以及include标签解析所涉及的路径都需要拼接该前缀例如 lib/jekyll/static_file.rb、lib/jekyll/tags/include.rb。4.2.1 的修复正是让include标签及相关路径解析尊重collections_dir配置PR #8756从而保证增量模式下能正确感知集合内文档的变更。增量模式的启用方式CLIjekyll build --incremental/jekyll serve --incremental-I简写见 lib/jekyll/command.rb配置_config.yml中设置incremental: true默认false见 lib/jekyll/configuration.rb。该流程的端到端行为在 features/incremental_rebuild.feature 中由 Cucumber 场景覆盖单元层面的 mtime/依赖判断逻辑见 test/test_regenerator.rb。如何验证你已正确升级确认版本号jekyll --version应输出4.2.1或更高也可直接查看 lib/jekyll/version.rb 确认仓库当前版本。验证 site.url 行为在 development 环境下运行jekyll serve在模板中输出{{ site.url }}应显示本地服务器地址运行jekyll build后输出应为_config.yml中的正式值。验证可变属性在页面模板中使用{{ page.content }}或依赖content的布局如 docs/_layouts/default.html渲染确认输出与页面实际内容一致。验证增量再生配置collections_dir后以--incremental模式启动修改集合内某篇文档确认对应输出被重新生成且.jekyll-metadata中的 mtime 记录同步更新。小结Jekyll 4.2.1 虽然是小版本却是一次典型的回归修复范本既有对 v4.2.0 激进改动的理性回退site.url覆盖、Liquid 可变属性也有对历史债务的补课collections_dir增量再生。三个修复共同保障了jekyll serve本地开发与jekyll build生产构建两条工作流的稳定衔接。对使用 4.2.0 的用户而言升级到 4.2.1或当前仓库所代表的 4.4.x 系列即可同时消除绝对链接失效与可变属性渲染异常对插件与主题开发者而言理解 Drop 的可变属性语义lib/jekyll/drops/drop.rb和增量再生依赖机制lib/jekyll/regenerator.rb能帮助你在后续版本中规避同类问题。【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考