Jekyll Sass Converter 3.0 迁移指南从 libsass 到 Dart Sass 的架构升级【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyllJekyll Sass Converter 3.0 是随 Jekyll 4.3 及以上版本一同发布的重大版本更新其核心变化是彻底弃用sassc即 libsass 绑定改用sass-embeddedgem 作为 Dart Sass 的接口将样式表转换引擎切换到当前 Sass 官方主推、仍在积极开发中的实现。本文以 Jekyll Sass Converter 3.0 发布公告为骨架结合当前仓库源码与配置完整梳理 v3.0 的迁移要点、被移除的配置选项、行为差异以及升级后的实际使用方式帮助读者平滑完成从 Ruby Sass / libsass 工作流到 Dart Sass 工作流的过渡。一、为什么升级libsass 已被废弃发布公告明确指出v3.0 之前 Jekyll Sass Converter 依赖sasscgem 完成 Sass 编译而sassc底层接口的是libsass——Sass 的次级实现。libsass 的维护者已经宣布弃用该项目因此继续基于sassc构建转换器不再可持续。v3.0 的应对方案是改用sass-embeddedgem它充当Dart SassSass 当前的主要实现、仍在积极开发与 Ruby 之间的桥接层。这意味着从 v3.0 开始Jekyll 站点的 Sass/SCSS 编译由 Dart Sass 完成。这一变化是上游实现层面的替换对最终输出的 CSS 产物而言绝大多数现有站点无需改动即可继续工作但由于Dart Sass 与旧版 Ruby Sass 并不完全兼容部分依赖旧实现特性的配置与用法必须在升级时调整——这正是下文迁移指南要解决的问题。二、环境要求v3.0 对运行环境提出了明确的下限要求原文即如此适用于所有平台项目最低版本Ruby2.6.0所有平台Rubygems3.3.22仅 Linux 平台需要说明的是这里的 Ruby 版本下限是 jekyll-sass-converter 3.0 自身的要求。若与 Jekyll 4.3 一同使用还应同时满足 Jekyll 本身的版本约束——当前仓库的 jekyll.gemspec 声明 Jekyll 4.x 要求 Ruby 2.7.0因此实际升级时建议以两者中更高的版本为准。同时仓库对 jekyll-sass-converter 的依赖声明为 2.0, 4.0见 jekyll.gemspec即 Jekyll 4.3 起会安装 3.x 系列。三、迁移指南被移除的配置选项1. 移除sass.implementation选项v2.2.0 曾引入sass.implementation配置项允许用户在多个 Sass 实现之间切换。由于 v3.0.x 中sass-embeddedDart Sass是唯一受支持的实现该选项已被移除。升级后_config.yml中任何形如implementation:的配置都应删除。2. 移除sass.add_charset选项v2.x 时代转换器会在sassify/scssify过滤器的输出中自动写入charset UTF-8;声明或UFEFF字节序标记 BOM。v3.0 起转换器不再输出这两类内容因此冗余的sass.add_charset选项也随之失效。这里需要解释sassify/scssify是什么它们是 Jekyll 内置的 Liquid 过滤器用于在模板或文件中把 Sass/SCSS 字符串就地转换为 CSS。其实现位于 lib/jekyll/filters.rb通过find_converter_instance找到对应的Jekyll::Converters::Sass/Jekyll::Converters::Scss转换器实例并调用其convert方法。仓库测试 test/test_filters.rb 中也验证了这两个过滤器的基本行为如sassify($blue:#123456; p{color: $blue})这类字符串转换。3. 移除sass.line_comments选项sass-embedded不支持sass.line_comments选项。该选项原本用于在输出的 CSS 中生成源码行注释方便调试定位升级后需从配置中移除如需类似调试能力可改用 Dart Sass 生态中其他调试手段但不能再通过该配置项实现。四、迁移指南行为与导入方式的变更除选项移除外v3.0 还收紧了若干导入行为这些收紧实际上源于旧版转换器的bug 副作用——官方选择在 v3.x 中修正而由于这些行为已在生产环境大量使用v2.x 分支会保留原样。1. 不再支持非标准扩展名的导入sass-embedded只允许导入扩展名为.sass、.scss或.css的文件。特别要注意扩展名为.css的文件中如果书写 SCSS 语法将直接报语法错误。升级前应检查所有import的文件是否使用了这三种扩展名之一。2. 不再支持相对站点源目录site source的导入在 v2.x 中即使站点源目录没有被列入 Sass 的load_paths选项转换器也允许使用相对站点源目录的路径进行导入——这是转换器的一个 bug 副作用官方因该行为在线上被广泛使用而在 v2.x 中保留。v3.x 中这类导入开箱即用将不再生效。如果需要继续使用相对站点源目录的导入必须把.表示当前目录即站点源目录显式加入load_paths选项例如sass: load_paths: - .3. 不再支持与父文件同名的导入v2.x 中转换器允许从sass_dir或load_paths导入与父文件同名的文件同样源于一个 bug 副作用v2.x 保留原样。例如在css/main.scss中import main试图导入_sass/main.scss这种做法在 Jekyll 4 中本就不被允许。v3.x 中这类导入会形成循环导入circular import。修复方式有两种重命名父文件或导入目标文件使二者不同名在import中使用从父文件出发的完整相对路径。仓库文档 Sass/SCSS 配置说明 也提示VSCode 中对import main;的警告可以忽略不影响 SCSS 功能但 Jekyll 4 确实不允许同名 sass 页面如css/main.scss导入同名的_sass/main.scss局部文件——这与上述循环导入问题同源。4. Dart Sass 与 Ruby Sass 的行为差异除了上述迁移点Dart Sass 与 Ruby Sass 之间还存在着若干有意的行为差异官方文档将其汇总为 Behavioral Differences from Ruby Sass 清单。升级后若发现输出样式与旧版有出入应优先排查该清单中的差异项例如函数行为、运算精度、错误信息格式等方面。本仓库无法复现该清单全文建议以 Dart Sass 官方文档为准进行核对。五、升级后的实际使用与 Jekyll 的集成方式升级到 v3.0 后Jekyll 的 Sass 工作流整体保持不变以下内容均基于当前仓库可验证。1. 文件如何被识别与处理Jekyll 通过扩展名识别 Sass 资产lib/jekyll/convertible.rb中定义了sass_file?见 convertible.rb仅当扩展名为.sass或.scss时返回 trueasset_file?convertible.rb则把 Sass/SCSS 与 CoffeeScript 一并归类为资产文件这类文件不会套用页面布局place_in_layout?返回 false。使用方法与 v2.x 完全一致在站点源目录中创建带.sass或.scss扩展名的文件并以两行三横线空 front matter开头例如css/styles.scss构建后输出到目标目录下对应位置css/styles.css。详见 Assets 文档。2.sass_dir局部文件目录与导入查找路径所有import引用的局部文件partials应放在sass_dir中其默认值为source/_sass。若使用import需在_config.yml中显式声明sass: sass_dir: _sass注意两点来自 Assets 文档 与 Sass 配置文档sass_dir仅作为 Sass 导入的查找路径load pathJekyll 本身并不直接跟踪这些文件因此该目录下的局部文件不应包含空 front matter否则不会被按预期转换该目录只应存放被导入的内容sass_dir等sass配置中的目录路径是相对于站点source目录解析的而不是相对于_config.yml所在位置。本仓库自带的 docs/css/screen.scss 就是一个典型示例它以import mixins;、import normalize;、import gridism;、import pygments;、import font-awesome;、import fonts;、import docsearch;、import style;的方式引入docs/_sass/下的多个局部文件——这正是 v3.0 仍然支持的常规导入方式。3. 输出样式与完整配置示例style选项仍然有效用于控制 CSS 输出格式可取值包括 Sass 支持的任何输出风格如expanded、compressed。例如本仓库自己的 docs/_config.yml 就使用了压缩输出sass: style: compressed一个 v3.0 兼容的完整配置示例合并了迁移要点sass: sass_dir: _sass # 局部文件目录也是默认导入查找路径 style: compressed # 输出样式expanded / compressed 等 # 以下为 v3.0 已移除的选项切勿再写 # implementation: ... # add_charset: ... # line_comments: ... # 如需支持相对站点源目录的导入显式添加 # load_paths: # - .六、升级检查清单综合发布公告与仓库信息从 v2.x 升级到 v3.0 时建议按以下顺序自查环境确认 Ruby 版本不低于 2.6.0Linux 平台确认 Rubygems 不低于 3.3.22配置清理从_config.yml的sass:段中移除implementation、add_charset、line_comments三个选项导入扩展名检查所有import文件确保扩展名为.sass、.scss或.css且.css文件中不得出现 SCSS 语法相对站点源目录的导入若仍在使用需在load_paths中显式加入.同名文件导入排查是否存在父文件导入同名列如css/main.scss导入_sass/main.scss的情况通过重命名或使用完整相对路径修复输出差异构建后比对新旧 CSS 输出如遇差异查阅 Dart Sass 官方的 Behavioral Differences from Ruby Sass 清单确认是否为有意行为变化。完成上述调整后站点即可在 Jekyll 4.3 上以 Dart Sass 作为转换引擎正常构建享受到 Sass 官方主推实现带来的持续维护与演进。【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
