SourceMap不匹配主因是映射路径或链路中断：Dart Sass CLI默认关闭，Webpack/Vite中任一loader漏配sourceMap:true均导致CSS行号无法跳转.scss文件。
SourceMap 不匹配不是“没生成”，而是映射路径或链路断在某个环节——Dart Sass CLI 默认关闭，Webpack/Vite 中任意 loader 或插件漏配 sourceMap: true 都会导致浏览器看到 CSS 行号却点不到 .scss 文件。
CLI 编译时 --source-map 参数位置和模式必须正确
Dart Sass 1.50+ 版本起，--source-map 不是可选开关，而是必须显式声明且位置敏感的参数。
-
sass src/main.scss dist/main.css→ 完全不生成 .map 文件，无警告 -
sass --source-map src/main.scss dist/main.css→ ✅ 正确：生成独立main.css.map -
sass --embed-source-map src/main.scss dist/main.css→ ⚠️ map 内联进 CSS 底部，体积膨胀，仅适合本地快速验证 - 参数顺序错（如写成
sass src/main.scss dist/main.css --source-map）→ 被忽略，静默失败
Webpack 中 sourcemap 是跨 loader 的传递链，漏一环就断
只在 sass-loader 里设 sourceMap: true 不够，CSS 映射需经 css-loader、postcss-loader（若使用）、MiniCssExtractPlugin 多层透传。
-
devtool不能用eval或cheap-module-eval-source-map：它们不支持 CSS 层映射 -
sass-loader必须显式传{ sourceMap: true }，且implementation指向dart-sass（node-sass已弃用） -
css-loader的options.sourceMap也得为true，否则会丢掉原始行号信息 -
MiniCssExtractPlugin默认把sourceMappingURL写成绝对路径，需加publicPath: ''强制相对路径
Vite 里 css.devSourcemap 和 sassOptions.sourceMap 必须同时开
css.devSourcemap: true 只控制 CSS 层处理链（如 PostCSS），但 Sass 编译本身是另一层，需单独启用。
立即学习“前端免费学习笔记（深入）”；
- 必须在
vite.config.js中写：css: { devSourcemap: true, preprocessorOptions: { sass: { sourceMap: true } } } - 拼写错误常见：
sourceMap（驼峰）≠devSourcemap（中划线），Vite 对大小写和连字符敏感 - 若用了自定义
@use '=/styles'别名，检查插件是否适配 importer，否则sources字段可能为空或路径越界 - 生成的
.css.map文件里sources值应为项目内可访问的相对路径，如["button.scss", "mixins/_reset.scss"]，绝不能出现/Users/xxx/或../../outside-project/
@use 导致跳转行号偏移，不是 bug 是扁平化行为
Dart Sass 的 @use 会让所有被引入的模块（mixin、function、variable）在逻辑上“合并”进当前上下文，sourcemap 把它们统一映射到一个扁平结构里。
- 你点击某条 CSS 规则，跳转位置可能是
_mixins.scss里的@mixin btn定义处，而非你正在编辑的page.scss - 这不是配置错误，是设计行为；调试时容易误判修改未生效
- 右键 DevTools Sources 面板中的 .scss 文件 → “Blackbox Content Script”，再刷新页面，跳转会退回到上一级映射（比如从
_mixins.scss退到main.scss） - 小项目可临时用
--source-map-include-sources把原始 SCSS 内容直接塞进 .map，绕过路径解析（但文件体积增大）
最常被忽略的是：.map 文件存在 ≠ 浏览器能加载它。检查 Chrome DevTools → Network 标签页，过滤 .map，确认 status 是 200 且响应体是合法 JSON；如果返回 404 或 HTML 内容，说明开发服务器没暴露对应路径，或 sourceMappingURL 注释里的路径前缀错了。
