jekyll sass converter在jekyll 2.0.0+中默认集成，无需手动添加gem；但需正确配置_sass目录存放partials、入口文件置于assets/等可识别路径，并在_config.yml中设置sass: style: compressed与sourcemap: always等有效选项。

jekyll-sass-converter 在现代 Jekyll（2.0.0+）中已是默认集成的 Sass 处理器，**无需手动添加 gem**，除非你用的是极老版本或自定义构建流程。但配置仍需明确，否则 Sass 文件不会被识别或编译。

确认 Jekyll 是否已启用 Sass 支持

运行 bundle exec jekyll build --verbose，观察输出中是否出现类似 Rendering Sass: assets/main.scss 的日志。如果没有，说明 Sass 转换未触发——常见原因是文件路径不在默认扫描范围内，或 _config.yml 中禁用了相关行为。

sass_dir 必须指向正确的源目录

Jekyll 默认只扫描 _sass/ 目录下的 .scss 或 .sass 文件（注意：是 partials，即以 _ 开头的片段），而入口文件（如 assets/main.scss）必须放在 Jekyll 能“看到”的路径下，且不能在 _sass/ 内直接作为入口。

• _sass/ 是存放 _variables.scss、_layout.scss 等 partials 的位置，Jekyll 自动将其加入 Sass load path
• 入口文件建议放在 assets/ 下（如 assets/css/style.scss），并确保该路径在 include 列表中（Jekyll 默认包含 assets/）
• 若改用其他目录（如 src/scss/），必须在 _config.yml 中显式声明：

  sass:<br>  sass_dir: src/scss

• 不要把入口文件和 partials 混放——比如把 main.scss 也丢进 _sass/，Jekyll 会跳过它（因认为是 partial）

sass 配置项写法与常见陷阱

_config.yml 中的 sass: 块控制编译行为，不是所有选项都有效，尤其 v3.x 后移除了旧参数。以下是最简且安全的配置：

sass:<br>  style: compressed<br>  sourcemap: always<br>  sass_dir: _sass

• style 可选 :compressed 或 :expanded（注意冒号，YAML 中是 symbol，不是字符串）
• sourcemap: always 才能生成 .css.map；true 在 v3.x 中已被忽略，仅 always 或 never 有效
• load_paths 若需额外引入路径（如 node_modules），必须用数组格式：load_paths: ["node_modules"]，且路径需相对于站点根目录
• 不要写 add_charset: false 或 line_comments: false —— 这些在 v3.x 中已彻底移除，会导致 Jekyll 启动报错 unknown configuration key 'add_charset'

为什么 main.scss 改了但 CSS 没更新？

这通常不是插件问题，而是 Jekyll 的依赖追踪机制没捕获到变更。Sass 编译依赖于 @import / @use 显式声明的引用链。如果你用的是 @use（Dart Sass 推荐），确保：

• 所有被 @use 的模块都在 _sass/ 下，且文件名不带 _（Dart Sass 要求模块名与文件名一致，@use "variables" 对应 _sass/variables.scss）
• 入口文件中没有遗漏 @use，或误用了 @import（v3.x 仍支持，但不推荐）
• 修改 partial 后，必须保存入口文件（哪怕只加个空格）才能触发重编译——Jekyll 不监听 _sass/ 下的改动，只监听入口和其直接依赖

最稳妥的调试方式是删掉 _site/assets/ 和 .jekyll-cache/，再跑 bundle exec jekyll build。