Jekyll 版本升级全指南从 0.x 迁移到 4.x 的路线图与源码级避坑手册【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyllJekyll 每发布一个主版本major version都会带来命令体系、配置项、默认行为与依赖关系的调整跨大版本升级如从 v2.x 到 v3.x往往伴随链接失效、插件不兼容甚至帖子凭空消失等头疼问题。本文以官方升级指南为主线完整梳理从 0.x 一路升级到 4.x 的每一步变化并结合当前仓库源码解释底层行为帮助你在升级 Jekyll 站点时做到心中有数、平滑过渡。读完本文你将掌握升级前的环境检查方法、各主版本的破坏性变更清单、以及升级后的验证思路。升级前确认当前版本与运行环境动手升级之前先确认自己当前所处的版本与运行环境。执行以下命令查看 Jekyll 与 Ruby 版本jekyll -v ruby -vRuby 版本是升级的硬性门槛。根据仓库中的 docs/_data/ruby.ymlJekyll 4 要求至少Ruby 2.7.0min_version: 2.7.0该文件还给出了参考输出如ruby 3.4.1。在 3.x 系列中自 3.2 起也已要求 Ruby 2.1。如果你尚未安装或想快速生成一个测试站点验证升级结果可直接运行gem update jekyll jekyll new SITENAMEjekyll new会创建一个全新的、带基础骨架的 Jekyll 站点目录适合在升级前做对照实验。保持最新次要更新与补丁升级官方强烈建议尽可能频繁地更新 Jekyll以便及时获得最新的 bug 修复而不是攒到跨大版本时一次性迁移。如果你按照推荐方式使用 Bundler 管理依赖运行bundle update jekyll或者直接bundle update这会把你项目Gemfile中锁定的所有 gem 一并更新到各自的最新版本受版本约束影响。如果你没有使用 Bundler则运行gem update jekyll如果你是通过github-pagesgem 在 GitHub Pages 上运行站点升级流程类似更新github-pagesgem 本身即可其内部锁定的 Jekyll 版本会随之更新。主要版本升级路线总览跨大版本升级涉及的行为变化各有侧重官方针对三个阶段分别撰写了专门指南本文后续小节将逐一展开升级路径核心变化对应指南0.x → 1.x / 2.x命令子命令化、绝对 permalink 默认化、引入草稿与--config从 0.x 升级到 2.x2.x → 3.x依赖裁剪、未来帖子默认关闭、Rouge 取代 Pygments、相对 permalink 移除从 2.x 升级到 3.x3.x → 4.x模板解析缓存、post_url自动合并 baseurl、排除项增强、Kramdown v2从 3.x 升级到 4.x从 0.x 升级到 1.x / 2.x拥抱子命令时代命令体系重构build与serve子命令在 1.x 之前生成站点直接运行jekyll本地预览则用jekyll --server。从 1.x 开始Jekyll 引入明确的子命令构建用jekyll build预览用jekyll serve。随之而来的是配置方式的改变原来在_config.yml中写server: true或watch: true的做法被废弃改为在命令行使用--watch标志jekyll serve --watch jekyll build --watch绝对 Permalink 成为默认Jekyll 1.0 为子目录中的页面引入了绝对 permalink相对于站点根目录从 2.0 起绝对 permalink 默认启用可显式关闭到 3.0相对 permalink 的兼容性被彻底移除详见后文。草稿文章Draft Posts从这一代开始Jekyll 支持先写草稿、发布前预览在站点源码目录下新建_drafts文件夹与_posts平级在_drafts中添加 Markdown 文件用jekyll serve --drafts预览。需要注意草稿不带日期。帖子名需要2013-07-01-my-draft-post.md这样的日期前缀而草稿直接命名为期望的文章标题即可例如my-draft-post.md因为草稿尚未发布。自定义配置文件与--config级联合并除了命令行传参这一代还支持通过--config一次性指定一个或多个自定义配置文件便于区分环境或编程式覆盖用户默认值。配置文件的合并规则是从右向左级联覆盖例如jekyll serve --config _config.yml,_config-dev.yml当左右两个文件含有相同键时右侧的_config-dev.yml的值会覆盖左侧_config.yml。注意一旦使用--config默认的_config.yml会被忽略因此需要把基础配置也显式列进去。相应地以下命令行标志从这一代起被弃用--no-server--no-auto改用--no-watch--auto改用--watch--server--url--maruku、--rdiscount、--redcarpet--pygments--permalink--paginate1.0 新增的配置选项升级前应检查旧配置文件是否用到了以下 1.0 引入的选项并确认用法正确excerpt_separator文章摘要分隔符仓库默认值为\n\n见 lib/jekyll/configuration.rb 的DEFAULTShost开发服务器绑定地址默认127.0.0.1include需要显式纳入生成目录的文件列表默认[.htaccess]keep_files生成时保留的目标目录文件默认[.git, .svn]layouts布局目录名现为layouts_dir默认_layoutsshow_drafts是否构建草稿也可用--drafts标志timezone站点时区默认使用本机时区url站点域名配合absolute_url过滤器生成绝对 URL。baseurl与多环境部署--baseurl标志让同一站点可以同时用于本地预览与线上部署。做法是先在_config.yml中写入生产环境的baseurl然后在模板中把相对 URL 前缀改为 {% raw %}{{ site.baseurl }}{% endraw %}本地预览时通过jekyll serve --baseurl /传入本地 baseurlJekyll 会按需替换保证两套环境链接都正确。一个经典陷阱是双前导斜杠帖子/页面的 URL 本身以/开头如post.url /2013/06/05/my-fun-post/若site.baseurl也是/直接拼接会得到//2013/06/05/...导致链接失效。因此建议仅在baseurl非默认值/时才做前缀拼接。从 2.x 升级到 3.x一次彻头彻尾的整理3.x 是一次大幅瘦身与行为修正的版本涉及数据模型、依赖、渲染器与配置默认值等多个层面。site.collections遍历方式的改变2.x 中遍历site.collections得到的是[label, collection_object]二元数组3.x 直接 yield 集合对象本身。模板中的转换规则collection[0]改为collection.labelcollection[1]改为collection如果你曾用site.collections.myCollection按名取值3.x 中请改为{% raw %}{% assign myCollection site.collections | where: label, myCollection | first %}{% endraw %}Textile 原生支持移除3.0 不再内置 Textile 支持需要使用 jekyll-textile-converter 插件来处理.textile文件。被移除的依赖包以下依赖从 3.0 起不再默认打包若用到对应功能必须显式安装并在Gemfile中声明jekyll-paginate旧式分页方案jekyll-coffeescriptCoffeeScript 处理jekyll-gistgistLiquid 标签pygments.rbPygments 高亮器redcarpetMarkdown 处理器toml配置文件的 TOML 替代格式classifier-rebornsite.related_posts相关功能。future 帖子默认关闭2.x 中--future标志被意外地默认启用3.x 修正为--future默认禁用。也就是说日期晚于当前系统时间的帖子默认不会被构建需要显式传--future才会生成jekyll build --future jekyll serve --future这一默认值同样体现在仓库源码中在 lib/jekyll/configuration.rb 的DEFAULTS里future false。例外情况是 GitHub Pages 站点为保持历史一致性其--future依然默认启用。layout元数据独立成变量2.x 及之前布局layoutfront matter 中的元数据会被合并进page变量容易造成数据合并的混乱与意外行为。3.x 起布局自身的数据统一通过layout变量访问。例如布局 front matter 中有class: my-layout则在布局内通过 {% raw %}{{ layout.class }}{% endraw %} 获取。默认语法高亮器更换为 Rouge3.0 首次更换默认语法高亮器highlight标签与反引号代码块默认使用 Rouge 而非 Pygments.rb。Rouge 是纯 Ruby 实现无需外部 Python 依赖但部分 Pygments 专属选项如hl_lines在 Rouge 下可能不可用。若确需回到 Pygments可在_config.yml中设置highlighter: pygments并执行gem install pygments.rb或向Gemfile添加gem pygments.rb。仓库当前默认配置即为highlighter rouge见 lib/jekyll/configuration.rb。相对 Permalink 移除3.0 起相对 permalink 被移除若站点由 2.x 及以下创建build/serve时可能报错。修复方法是从_config.yml删除以下行relative_permalinks: truePermalink 不再自动追加尾斜杠2.x 中由permalink:字段构造的 URL 会自动补一个尾斜杠/3.x 不再自动追加。例如permalink: /:year-:month-:day-:title在 2.x 生成example.com/2016-02-01-test/并生成同名文件夹在 3.x 则生成2016-02-01-test.html与 URLexample.com/2016-02-01-test旧链接会 404。如需保持原 URL请在permalink:字段末尾手动加/例如permalink: /:year-:month-:day-:title/。时区导致的帖子消失问题升级后若发现帖子全部消失先尝试在_config.yml中加入future: true验证若帖子回来了说明是 Ruby 解析时间与本地时区不一致导致帖子被判定为未来时间。正确做法是移除future: true并为每篇帖子显式添加时区偏移。例如在加利福尼亚--- date: 2016-02-06 19:32:10 ---改为注意末尾偏移量--- date: 2016-02-06 19:32:10 -0800 ---分类目录结构变化如果之前把分类组织为/_posts/code/2008-12-24-closures.md需要重构目录把分类目录放到_posts之上/code/_posts/2008-12-24-closures.md。从 3.x 升级到 4.x性能与兼容性的双重调整4.x 在构建性能与渲染架构上做了较大改动同时清理了大量历史遗留行为。Ruby 版本要求Jekyll 4 至少需要 Ruby 2.7.0先执行ruby -v确认。满足版本后即可更新gem update jekyllpost_url标签自动应用 baseurl4.0 起post_url标签在内部集成了relative_url过滤器会自动把站点的baseurl前缀拼到帖子 URL 上。因此不要再手动拼接site.baseurl否则会出现重复前缀{% highlight diff %}{{ site.baseurl }}/{% post_url 2018-03-20-hello-world.markdown %}{% post_url 2018-03-20-hello-world.markdown %} {% endhighlight %}源码可以印证这一行为在 lib/jekyll/tags/post_url.rb 中PostUrl标签include Jekyll::Filters::URLFilters渲染时对匹配到的帖子调用relative_url(post)后返回而relative_url在 lib/jekyll/filters/url_filters.rb 中实现其compute_relative_url会把站点配置的baseurl经sanitized_baseurl去除尾部斜杠、ensure_leading_slash保证前导斜杠拼接到输入 URL 之前。另外post_url的参数支持直接写文件名如2018-03-20-hello-world.markdown标签内部通过POST_PATH_MATCHER正则\A(./)*?(\d{2,4}-\d{1,2}-\d{1,2})-([^/]*)\z解析出路径、日期与 slug再与站内帖子逐一比对。模板渲染机制解析一次、缓存复用为提升整体构建速度4.0 改变了模板的解析与渲染方式每个模板只解析一次并缓存之后按需多次渲染。其代价是部分社区插件可能不再按旧逻辑工作。从源码看lib/jekyll/liquid_renderer.rb 维护一个cacheLiquidRenderer#cache按文件名存取解析结果而 lib/jekyll/liquid_renderer/file.rb 的parse方法执行renderer.cache[filename] || Liquid::Template.parse(content, :line_numbers true)正是同一文件只解析一次的实现render之前会通过reset_template_assigns清空template.instance_assigns避免多次渲染间状态互相污染。渲染过程还通过measure_time/measure_bytes/measure_counts统计每个文件的耗时、字节数与渲染次数可用于--profile性能分析。未输出集合中的静态文件除posts外的集合可以同时包含 Markdown 文档与静态资源但若该集合未配置元数据output: true其文档与静态资源都不会输出到目标目录。如果需要集合内容出现在生成的站点中必须在_config.yml中为该集合设置output: true。插件作者须知如果你的插件依赖site.liquid_renderer.file(path).parse(content)注意返回值templateLiquid::Template实例对同一path而言始终是同一个对象。渲染时仍按传入的payload进行因此请勿在插件实例中 memoize 或缓存payload。如果业务上要求每次拿到不同的template可以直接绕过缓存调用Liquid::Template- template site.liquid_renderer.file(path).parse(content) template Liquid::Template.parse(content)默认排除项增强4.0 增强了默认排除数组exclude且不再被用户配置中的exclude覆盖——用户的排除条目只会被追加到默认数组中去重后。默认排除项如下# default excludes exclude: - .sass-cache/ - .jekyll-cache/ - gemfiles/ - Gemfile - Gemfile.lock - node_modules/ - vendor/bundle/ - vendor/cache/ - vendor/gems/ - vendor/ruby/这与仓库源码中Configuration的add_default_excludes逻辑一致见 lib/jekyll/configuration.rb站点配置在DEFAULTS基础上深合并用户配置后追加默认排除项。若要强制处理已被排除的目录/文件把它加入include数组即可# 覆盖默认 include 数组默认值为 [.htaccess] include: - .htaccess - node_modules/uglifier/index.js上述配置只让 Jekyll 输出node_modules/uglifier/index.js而忽略node_modules中的其他文件该目录默认被排除。注意默认include数组仍会被用户配置中的include整体覆盖所以需要保留.htaccess时务必把它一并写入。Kramdown v24.0 彻底放弃对kramdown-1.x的支持改用 Kramdown v2。kramdown 从 v2.0 起将部分功能拆分为独立扩展 gem需要按需安装。其中kramdown-parser-gfm会随 Jekyll 4.0 自动安装仓库默认 kramdown 配置中input: GFM即依赖它见 lib/jekyll/configuration.rb 的DEFAULTS其余扩展需用户根据需求在Gemfile中显式声明。此外kramdown-converter-pdf不会被 Jekyll 核心直接使用。若需要把 Markdown 转为 PDF必须编写一个继承Jekyll::Converter的插件例如module Jekyll External.require_with_graceful_fail kramdown-converter-pdf class Markdown2PDF Converter safe true priority :low def matches(ext) # match only files that have an extension exactly .markdown ext ~ /^\.markdown$/ end def convert(content) Kramdown::Document.new(content).to_pdf end def output_ext .pdf end end end关于编写转换器插件所需的完整方法matches、convert、output_ext等可参考 插件转换器指南。另外提供版本化 Jekyll 环境镜像的厂商如 Docker 镜像、GitHub Pages 等需要在自己的发行版中手动白名单 kramdown 的扩展 gem。弃用配置选项清理Jekyll 4.0 移除了此前多个版本中已弃用的全部遗留配置选项不再输出弃用警告也不再将其值优雅地映射到新选项。具体行为取决于键本身——要么被直接忽略要么因键仍有效但值类型不合法而抛出InvalidConfigurationError。升级前请逐一核对_config.yml中是否还残留旧版配置键。升级后的验证清单完成跨版本升级后建议按以下清单系统验证站点构建无错误运行jekyll build确认无InvalidConfigurationError、无 Liquid 渲染错误、无 permalink 相关报错帖子完整性确认日期在未来的帖子行为符合预期是否需要--future检查是否有帖子因时区问题消失链接完整性重点检查post_url标签是否已去掉手动拼接的site.baseurl以及 permalink 尾部斜杠变化是否导致旧链接 404集合输出确认所有设置了output: true的集合及其静态资源正常输出插件兼容性逐个验证第三方插件是否受模板缓存与依赖裁剪影响必要时改用Liquid::Template.parse并补充被移除的依赖 gem高亮与 Markdown确认代码高亮Rouge与 kramdown 扩展如 GFM按预期工作本地预览用jekyll serve启动并抽查关键页面尤其是有baseurl的站点。无论从哪个大版本起步升级的本质都是行为变更清单 环境迁移。建议先在本地新建测试站点或使用jekyll new对照验证再对生产站点执行升级把风险控制在可回滚的范围内。【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
