Jekyll 默认的 sass-converter 编译失败是因为它依赖已停止维护且不兼容 Ruby 3.0+ 的旧版 Ruby Sass；应改用官方推荐的 dart-sass，通过全局安装 npm install -g sass、配置 config.yml 启用 jekyll-sass 插件并指定 implementation: dart，同时确保文件命名规范（@use 文件须以 开头）和路径正确。
为什么 Jekyll 默认的 sass-converter 会编译失败？
Jekyll 内置的 sass-converter 实际上早已被弃用，它依赖过时的 Ruby Sass（sass gem），而该 gem 自 2019 年起停止维护，且不兼容 Ruby 3.0+。你在 _config.yml 中写 sass: {} 或启用 plugins: [jekyll-sass-converter]，大概率会遇到 LoadError: cannot load such file -- sass 或 undefined method `css' 类错误。
- 别再安装
sassgem（旧版）或尝试降级 Ruby - 改用官方推荐的
dart-sass—— 它是唯一活跃维护的 Sass 实现，支持现代语法（如模块系统、@use） - Jekyll 4.3+ 原生支持
dart-sass，但需显式配置路径和扩展名
如何让 Jekyll 正确调用 dart-sass 编译 .scss 文件？
关键不是“插件”，而是让 Jekyll 把 .scss 文件识别为可处理的前端资源，并交由本地 dart-sass 执行。Jekyll 本身不编译 Sass，它只负责调度 —— 所以必须提前装好 CLI 工具并指定位置。
- 全局安装：
npm install -g sass（会提供sass命令） - 在
_config.yml中添加：plugins: - jekyll-sass
（注意：不是jekyll-sass-converter） - 确保
_sass/目录存在，且所有主入口文件（如_sass/main.scss）放在该目录下 - 在
_layouts/default.html或页面中引用：<link rel="stylesheet" href="/assets/css/main.css">，对应源文件路径应为assets/css/main.scss（Jekyll 会自动将同名.scss映射为.css输出）
为什么 @import 能用但 @use 报错？
因为默认 Jekyll 的 sass 配置使用的是较旧的“indented syntax”兼容模式，或未启用模块系统。Dart Sass 默认启用 @use，但 Jekyll 插件若没传参，可能仍走 legacy 模式。
- 在
_config.yml中强制指定引擎：sass: style: compressed load_paths: - _sass implementation: dart -
@use只能用于.scss（不能用于.sass），且所有被@use的文件必须以_开头（如_variables.scss） - 如果仍报
Invalid CSS after "@use"，检查是否误把.sass文件混入了_sass/—— Jekyll 会尝试用错误解析器处理它
开发时要不要用 watch 模式？怎么避免重复编译？
直接运行 jekyll serve 会触发内置的 Sass 编译流程，但响应慢、无增量、不报详细错误行号。更高效的做法是分离构建链：用 sass --watch 单独监听并输出到 _site/assets/css/，再让 Jekyll 忽略该路径的源文件。
立即学习“前端免费学习笔记（深入）”；
- 新建
package.json，加脚本："scripts": { "sass:watch": "sass --watch assets/css/main.scss:_site/assets/css/main.css --style=compressed" } - 启动两个终端：一个跑
npm run sass:watch，另一个跑jekyll serve --incremental - 在
_config.yml加上：exclude: - "assets/css/*.scss"
，防止 Jekyll 二次尝试编译同一文件 - 这样既能获得 Dart Sass 的实时错误定位（含行号），又避免 Jekyll 的 Ruby 层解析开销
真正麻烦的不是配置，而是混淆了「谁在编译」——Jekyll 不是编译器，它只是调度器；sass CLI 才是真正的编译器。搞清这个分工，很多报错就自然消失了。
