Jekyll 从 0.x 升级到 2.x 完全指南命令重构、绝对永久链接与多环境部署【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll本篇技术指南以 Jekyll 官方升级文档 docs/_docs/upgrading/0-to-2.md 为骨架系统梳理从 0.x 时代迁移到 Jekyll 1.0/2.0 时需要注意的全部变更命令行体系从裸命令重构为build/serve子命令、永久链接默认切换为绝对模式、草稿文章与自定义配置文件两大新能力的引入以及--baseurl多环境部署方案的落地。读完本文你将能对照仓库源码理解这些变更的底层机制并安全地把旧站点迁移到新版本。升级前的准备更新 Jekyll 并快速验证升级的第一步是获取最新版本gem update jekyll更新完成后可以用jekyll -v确认当前版本号。如果是从零开始、想快速体验新版本站点结构直接运行jekyll new SITENAME该命令会在SITENAME目录下生成一套「bare bones」的初始站点包含_config.yml、_posts、index.markdown等基础文件模板见 lib/site_template。需要留意的是docs/_docs/upgrading/2-to-3.md 中提到自 Jekyll 3.2 起对 Ruby 版本有最低要求 2.1因此升级前也建议检查运行环境的 Ruby 版本。Jekyll 命令体系重构从裸命令到build/serve子命令0.x 时代的用法比较隐晦直接运行jekyll生成站点用jekyll --server本地预览。从 v1.0 起Jekyll 引入了更清晰的子命令体系v2.0 及以后应使用jekyll build # 生成站点等价于旧版的 jekyll jekyll serve # 本地预览等价于旧版的 jekyll --server在仓库源码中可以看到这两个子命令的实际注册方式lib/jekyll/commands/build.rb 中通过prog.command(:build)注册并提供了别名c.alias :blib/jekyll/commands/serve.rb 中通过prog.command(:serve)注册同时保留了cmd.alias :server与cmd.alias :s作为兼容别名。配置项被命令行标志取代server: true与watch: true配合子命令重构本地预览与自动重建的方式也变了不要再用配置文件里的server: true改用jekyll serve不要再用配置文件里的watch: true改用--watch标志且它同时适用于jekyll serve和jekyll build。从源码看serve子命令在 action 中默认开启 watchlib/jekyll/commands/serve.rb 中opts[watch] true unless opts.key?(watch)而build子命令则只有在显式传入--watch时才进入监听重建lib/jekyll/commands/build.rb其底层监听逻辑委托给jekyll-watch外部 gemExternal.require_with_graceful_fail jekyll-watch。--watch、--drafts、--baseurl、--config等通用构建选项统一由 lib/jekyll/command.rb 的add_build_options方法注入到各子命令中。绝对永久链接Absolute Permalinksv2.0 起默认开启永久链接permalink是 Jekyll 生成 URL 的核心机制。在 v1.0 中Jekyll 引入了针对子目录中页面的绝对永久链接从 v2.0 起绝对永久链接由「opt-in」变为「opt-out」——即默认启用不再需要显式声明。旧行为相对永久链接子目录页面的 URL 相对其父目录计算新行为绝对永久链接页面 URL 始终相对于站点源目录source计算。为什么链接不能简单沿用旧写法URL 的生成逻辑集中在 lib/jekyll/url.rbJekyll::URL接收:template或:permalink通过占位符替换生成 URL并经过sanitize_url规整保证以单个/开头、折叠重复斜杠等。由于 URL 语义从「相对父目录」变为「相对站点源目录」旧站点中手写的相对链接如../about/在新版本下可能指向错误位置需要逐一核对。v3.0 的彻底移除提前规划升级文档中明确给出了预警相对永久链接功能将在 v3.0 被彻底移除。仓库源码印证了这一演进——lib/jekyll/site.rb 中的relative_permalinks_are_deprecated方法会在检测到relative_permalinks配置时直接终止构建Jekyll.logger.abort_with提示内容与 docs/_docs/upgrading/2-to-3.md 记录的报错信息一致。因此从 0.x 升级到 2.x 时建议同步从_config.yml中移除relative_permalinks: true或改用它jekyll doctor也会通过 lib/jekyll/commands/doctor.rb 的deprecated_relative_permalinks检查给出警告一步到位切换到绝对永久链接。草稿文章Draft Posts写作与预览两不误v1.0/2.0 让 Jekyll 首次支持「先写草稿、后发布」的工作流在站点源目录下与_posts同级新建_drafts文件夹把未完成的 Markdown 文件放进去用jekyll serve --drafts或jekyll build --drafts预览草稿效果。草稿不携带日期与正式文章不同草稿尚未发布、没有日期概念因此文件名不要写成2013-07-01-my-draft-post.md这种带日期前缀的形式直接使用你期望的最终文章标题即可例如my-draft-post.md。从源码可以清晰看到这一设计lib/jekyll/readers/post_reader.rb 中read_drafts使用Document::DATELESS_FILENAME_MATCHER无日期匹配器而read_posts使用Document::DATE_FILENAME_MATCHER日期匹配器——两类文件按不同的命名规范解析草稿是否被读取取决于配置项show_draftslib/jekyll/reader.rb 中site.posts.docs.concat(post_reader.read_drafts(dir)) if site.show_drafts命令行-D/--drafts标志在 lib/jekyll/command.rb 中定义最终映射到配置的show_drafts项。注意_drafts目录名以下划线开头属于 Jekyll 的特殊目录默认不会作为普通页面输出过滤规则见 lib/jekyll/entry_filter.rb 的special?判断只有在--drafts开启时其中的文档才会被渲染。自定义配置文件--config多文件级联从 0.x 升级到 2.x 的另一大能力是通过单个标志加载一整套自定义配置替代在命令行逐个传参。用法jekyll build --config _config.yml,_config-dev.yml jekyll serve --config _config.yml,_config-prod.yml关键规则文件列表用逗号分隔且不能带空格一旦使用--config默认的_config.yml将被忽略——如果你还想保留它必须显式把它也写进列表多个配置文件从右到左级联右侧文件的值覆盖左侧文件的同名键。例如jekyll serve --config _config.yml,_config-dev.yml中_config-dev.yml的取值优先生效。这一机制的底层实现在 lib/jekyll/configuration.rbconfig_files方法L141-L158解析override[config]若未指定则回退到源目录下的_config.yml并按yml → yaml → toml的顺序探测随后read_config_filesL191-L207按顺序逐个读取文件并通过Utils.deep_merge_hashes完成深合并——后读入的配置自然覆盖先读入的同名键这正是「右侧覆盖左侧」的根源。已废弃的命令行标志清单由于--config的出现以下旧标志已废弃对应的能力改由配置文件或新标志提供废弃标志替代方案--no-server不再需要使用jekyll build--no-auto--no-watch--auto--watch--serverjekyll serve--url在_config.yml中设置url--maruku/--rdiscount/--redcarpet在_config.yml中设置markdown--pygments在_config.yml中设置highlighter--permalink在_config.yml中设置permalink--paginate在_config.yml中设置paginate这些配置化方向的演进在 lib/jekyll/configuration.rb 的DEFAULTS中得到了完整体现markdown默认kramdown、highlighter默认rouge、permalink默认date风格、paginate_path等均以配置键形式存在命令行传入的覆盖值通过get_config_value_with_overrideL100-L102按「命令行覆盖 配置文件 默认值」的优先级生效。Jekyll 1.0 引入的新配置选项升级前请检查旧配置文件中是否已经出现以下 1.0 新增选项确保用法正确配置项作用默认值见 lib/jekyll/configuration.rb DEFAULTSexcerpt_separator定义摘要分隔符用于生成文章摘要\n\n空行host本地预览时绑定的主机地址127.0.0.1include显式包含默认被忽略的隐藏文件如.htaccess[.htaccess]keep_files生成_site时保留的文件/目录不覆盖删除[.git, .svn]layouts布局文件的目录名_layouts当前源码中为layouts_dirshow_drafts是否渲染_drafts中的草稿nil等价关闭由--drafts开启timezone指定时区如America/Los_Angeles用于日期解析nil使用本地时区url站点的完整生产 URL如https://example.com无默认按主机推导其中几个选项在源码中有直接体现excerpt_separator的默认值\n\n定义于 DEFAULTSlib/jekyll/configuration.rbkeep_files控制清理器在清空_site时保留哪些文件timezone与 2.x 时代的时区解析问题直接相关——若文章日期未带时区偏移Ruby 会按本地时区解析可能导致文章被判为「未来日期」而被跳过该问题在 docs/_docs/upgrading/2-to-3.md 中有详细说明与修复示例即在日期后追加偏移如-0800。Baseurl一套站点多环境部署很多场景下你需要让同一个 Jekyll 站点运行在多处先在本地预览再推送到 GitHub Pages 等生产环境。v1.0 引入的--baseurl标志让这件事变得简单。标准工作流在_config.yml中设置生产环境的baseurl例如/blog站点内所有相对 URL 都加上{{ site.baseurl }}前缀本地预览时用jekyll serve --baseurl /覆盖Jekyll 会临时替换为你传入的值保证两种环境下链接都正确。配置层面的默认行为是baseurl默认值为nil即挂载在根路径见 lib/jekyll/configuration.rb命令行-b/--baseurl URL标志定义于 lib/jekyll/command.rb。在服务端WEBrick 挂载时会把baseurl作为挂载路径传入lib/jekyll/commands/serve.rb 中server.mount(opts[baseurl].to_s, Servlet, destination, ...)打印的服务器地址也会带上该路径。前导斜杠陷阱重要所有文章和页面的 URL 本身都以/开头。当site.baseurl /时直接拼接site.baseurl post.url会出现双斜杠例如/拼上/2013/06/05/my-fun-post/得到//2013/06/05/my-fun-post/导致链接失效。因此官方建议仅在baseurl不是默认值/时才使用site.baseurl前缀拼接当baseurl恰好为/时直接用post.url/page.url即可避免双斜杠。URL 层的这一约束也与 lib/jekyll/url.rb 中sanitize_url的处理逻辑相呼应——它负责把..、./与重复斜杠规整为合法路径但模板拼接阶段的错误仍需你在写模板时规避。升级检查清单最后将本文全部要点汇总为一份可直接对照执行的清单运行gem update jekyll升级并用jekyll -v验证版本把脚本与习惯中的jekyll改为jekyll buildjekyll --server改为jekyll serve从_config.yml移除server: true与watch: true改用jekyll serve/jekyll build --watch移除relative_permalinks: true全面切换到 v2.0 默认的绝对永久链接并核对子目录页面的手写相对链接相对永久链接将在 v3.0 被移除详见 docs/_docs/upgrading/2-to-3.md如需草稿工作流新建_drafts目录文件不带日期前缀用jekyll serve --drafts预览用--config a.yml,b.yml替代散落的命令行参数记住右侧覆盖左侧、逗号后不加空格清理已废弃的标志--no-server、--auto、--server、--pygments、--permalink、--paginate等相关能力改由_config.yml配置核对 1.0 新增配置项excerpt_separator、host、include、keep_files、layouts、show_drafts、timezone、url是否按新语义使用部署到子路径的站点在_config.yml设置baseurl并在模板中前缀{{ site.baseurl }}注意避开双斜杠本地预览时用--baseurl /覆盖升级后运行jekyll doctor做一次健康检查相关检查逻辑见 lib/jekyll/commands/doctor.rb确认站点配置无遗留的兼容性问题。【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考