SCSS sourcemap失效90%是浏览器未加载有效映射，需先验证三件事：CSS末尾是否有合法sourceMappingURL注释、.map文件能否被浏览器直接访问且内容非空（sources字段非空）、Sources面板是否显示.scss文件名；再检查CLI参数顺序、loader链透传、插件兼容性及路径解析规则。
SCSS 编译后的 CSS 文件 sourcemap 失效，90% 的情况不是“没生成”，而是浏览器根本没加载到有效映射——先验证三件事，再调配置。
怎么确认 .css 文件末尾有 sourceMappingURL 注释
浏览器只认 CSS 文件最后一行的 /*# sourceMappingURL=xxx.css.map */，且必须是纯注释、无空行、无其他字符。手动加或构建工具覆盖都容易出错。
- 用
tail -n 1 dist/main.css（Linux/macOS）或记事本末尾查看，确认存在该注释 - 如果注释里路径是
../maps/main.css.map，但你的开发服务器只暴露/css/目录，浏览器就 404 —— 路径必须能被直接访问（比如http://localhost:3000/css/main.css.map） - Webpack/Vite 等工具通常自动注入，但若你用了自定义 PostCSS 插件或 lightningcss，可能删掉了这行；检查构建日志是否含 “Generated source map for”
如何验证 .css.map 文件本身是否有效
空的 .map 文件（如 {"version":3,"sources":[],"mappings":"","file":"style.css"}）说明编译器压根没建立映射，不是路径问题，是开关没打开。
- 用浏览器直接打开
.css.mapURL，看是否返回合法 JSON，sources字段是否非空（例如["button.scss", "mixins/_reset.scss"]） - Dart Sass 1.50+ 默认关闭 sourcemap，
sass src/main.scss dist/main.css不会生成有效内容；必须加--source-map且放在输入输出路径之前：sass --source-map src/main.scss dist/main.css - CLI 中用
--embed-source-map可绕过路径问题（map 内联进 CSS），适合本地快速验证，但体积大，别上生产
为什么 DevTools Sources 面板看不到 .scss 文件
看到 .css.map 且内容正常，但 Sources 里没有 sass 或 sources 节点？多半是 sources 字段里的路径解析失败。
立即学习“前端免费学习笔记（深入）”；
- 检查
.map文件中sources值：出现"/Users/xxx/project/src/button.scss"或"../../src/button.scss"就危险——前者是绝对路径，后者越界，浏览器无法定位 - Webpack 中需配
mini-css-extract-plugin的publicPath: ''，否则它默认写成http://localhost:3000/dist/main.css.map这类绝对 URL - Vite 用户注意：
css.devSourcemap: true控制 CSS 层链，但 Sass 编译还得显式设css.preprocessorOptions.sass.sourceMap: true，漏掉一个就断链
@use 导入导致跳转到错文件，怎么回到编辑中的 .scss
Dart Sass 的 @use 会让 sourcemap 把所有依赖模块“扁平化”进一个逻辑上下文，你点样式时跳转的位置，常是 _mixins.scss 里的 mixin 定义处，而不是你正在写的 main.scss。
- 这不是 bug，是设计行为：sourcemap 映射的是“实际参与编译的代码位置”，不是“你当前光标在哪”
- 右键 DevTools Sources 面板里的 .scss 文件 → “Blackbox Content Script”，再刷新页面，跳转会退回到上一级（比如从
_mixins.scss退到main.scss） - 想彻底避免偏移，可临时改用
@import（不推荐长期用），或在 CLI 编译时加--source-map-include-sources，把原始 SCSS 内容直接塞进 .map，跳转时就能看到真实文件结构
真正卡住人的从来不是“怎么开 sourcemap”，而是“开了之后谁在中间把它吃掉了”——CLI 参数顺序、loader 链透传、插件兼容性、路径解析规则，四者缺一不可。每次失效，优先查 .map 文件内容和浏览器 Network 面板里 .map 的响应状态码，比翻文档快得多。
