根本原因是浏览器未加载有效映射，90%由sourceMappingURL注释非法、.map文件404或sources路径越界导致；需依次验证注释合法性、.map可访问性及内容、sourcemap链路全开启。
SCSS 编译后 Source Map 无法映射到原始 .scss 文件，根本原因不是“没生成”，而是浏览器加载时根本没拿到有效映射——sourceMappingURL 注释非法、.map 文件 404、或 sources 字段路径越界，三者占失效原因的 90%。
检查 CSS 文件末尾的 sourceMappingURL 注释是否合法
浏览器只认 CSS 文件最后一行的 /*# sourceMappingURL=main.css.map */，且必须满足：
- 是纯注释，前后无空格、无其他字符（比如不能是
//# sourceMappingURL=...或带 JS 注入） - 必须是文件最后一行，后面不能有空行、不能紧跟
<script>或其他内容 - 路径必须能被浏览器直接访问（比如
http://localhost:3000/css/main.css.map），相对路径如../maps/main.css.map要确保开发服务器实际暴露该路径 - Webpack/Vite 通常自动注入，但若用了
lightningcss、自定义 PostCSS 插件或覆盖了 CSS 输出逻辑，这行可能被静默删掉；查构建日志是否有Generated source map for
验证 .css.map 文件本身是否可访问且内容合法
用浏览器直接打开 sourceMappingURL 指向的地址，确认返回的是合法 JSON，并重点看：
-
sources字段是否非空，例如["button.scss", "mixins/_reset.scss"] - 绝不能含绝对路径（如
/Users/xxx/project/src/button.scss），否则浏览器无法定位 - 也不能越界（如
../../outside-project/vars.scss），这类路径在开发服务器上根本不可访问 - Dart Sass 1.50+ 默认关闭 sourcemap：
sass src/main.scss dist/main.css完全不生成.map；必须加--source-map且放在输入输出路径之前：sass --source-map src/main.scss dist/main.css
Webpack 中 sourcemap 链路是否完整透传
SCSS → CSS → PostCSS → 最终 CSS 是一条链，漏一环就断：
立即学习“前端免费学习笔记（深入）”；
-
sass-loader必须显式设sourceMap: true，且implementation指向dart-sass（node-sass已弃用，不支持现代链路） -
css-loader的options.sourceMap也得为true，否则丢原始行号 - 若用了
postcss-loader（如 autoprefixer），同样要开sourceMap: true -
MiniCssExtractPlugin默认写绝对 URL，必须加publicPath: ''强制相对路径 -
devtool别用eval或cheap-module-eval-source-map：它们不支持 CSS 层映射
Vite 中两层 sourcemap 开关是否同时启用
css.devSourcemap 和 css.preprocessorOptions.sass.sourceMap 是两个独立开关，缺一不可：
-
css.devSourcemap: true只控制 CSS 层处理链（如 PostCSS），不影响 Sass 编译本身 -
css.preprocessorOptions.sass.sourceMap: true单独控制 Sass 编译层，漏掉就断在第一步 - 拼写敏感：
sourceMap（驼峰）≠devSourcemap（中划线），Vite 对大小写和连字符极其严格 - 若自定义了
includePaths或additionalData，Vite 会清空默认配置，sourceMap: true必须手动补上
最容易被忽略的是：即使所有配置都对，.map 文件里 sources 的路径仍可能因 @use 别名、server.host: true 或构建时路径解析规则而变成不可访问的 URL —— 这类问题不会报错，但点进去就是空白。调试时务必先打开浏览器 Network 面板，过滤 .map，看它是不是 404 或返回空 JSON。
