Source map 是调试 SCSS 的必需环节，非可选附加项；Sass CLI 1.50+ 默认禁用，须显式加 --source-map 参数，且需在构建链路中逐层透传（loader、插件、打包器），否则浏览器无法映射回源文件。
Source map 不是可选附加项，而是调试 SCSS 的必需环节；没配好它，你改了 $primary 却在浏览器里看不到效果，或断点打在 CSS 行却跳不到对应 SCSS 行——这根本不是代码问题，是构建链路断了。
为什么 sass --watch 默认不生成 .css.map
Sass CLI 从 1.50 版本起默认禁用 source map，必须显式声明。不加 --source-map 参数时，sass src/main.scss dist/main.css 只输出 CSS，连警告都不会报。
-
--source-map：生成独立.css.map文件（推荐） -
--embed-source-map：把 map 内容 base64 编码后塞进 CSS 底部（仅适合开发，体积大） -
--no-source-map：强制关闭（CI 环境常用） - 注意：
--source-map必须和输入输出路径一起写，单独写sass --source-map main.scss会失败
Webpack + sass-loader 下的 source map 配置陷阱
很多人以为在 sass-loader 里加 sourceMap: true 就够了，但漏掉了两个关键依赖：
- CSS 提取插件（如
mini-css-extract-plugin）也得开启sourceMap: true，否则提取出的 CSS 文件里没有sourceMappingURL注释 - 如果用了
css-loader，它的sourceMap选项也得为true，否则模块内联样式无法回溯 - Webpack 自身的
devtool值不能是eval或cheap-module-eval-source-map，它们不兼容 CSS source map；推荐source-map（全量）或inline-source-map（开发快）
Vite 和 Rollup 的差异点
Vite 开箱支持 SCSS source map，但需确认配置项是否启用：
立即学习“前端免费学习笔记（深入）”；
- Vite 项目中检查
vite.config.js是否有css: { devSourcemap: true }（注意拼写是devSourcemap，不是sourceMap） - Rollup 使用
rollup-plugin-scss时，插件选项里要传{ outputStyle: 'expanded', sourceMap: true }，且确保下游插件（如rollup-plugin-postcss）不覆盖或丢弃 map - Rollup 默认不生成 source map，即使插件开了，也要在
output.sourcemap设为true才写入文件
WebStorm File Watcher 的参数校验重点
WebStorm 的 File Watcher 界面看着简单，但几个参数错一位就静默失效：
-
Arguments字段必须包含--source-map，且位置要在输入输出路径之前（例如：--source-map --watch $FileName$:$FileNameWithoutExtension$.css） -
Output paths to refresh必须显式填$FileNameWithoutExtension$.css.map，否则 IDE 不识别新文件、不触发自动刷新 - 如果你用的是 Dart Sass（npm 安装），别再用旧 Ruby Sass 的
--sourcemap（带连字符）写法，Dart Sass 只认--source-map（两个短横） - 路径变量如
$FileParentDir$要配合输出目录层级使用，比如想输出到css/子目录，就得写$FileParentDir$/css/$FileNameWithoutExtension$.css
真正容易被忽略的，是 source map 的“传递性”——它必须从 Sass 编译器出发，经 loader、extract 插件、打包器层层透传，中间任何一环关掉或格式不匹配，浏览器开发者工具里看到的就只是压缩后的 CSS 行号。别急着怀疑变量覆盖逻辑或 @import 顺序，先打开生成的 CSS 文件，搜 sourceMappingURL，看它是否存在、路径是否可访问、内容是否 JSON 格式有效。
