Vite 的 css.sourcemap 默认开发环境为 true，但易被插件、lightningcss 或环境变量覆盖；需显式配置 css: { sourcemap: true }，并确保 lightningcss、自定义 importer、浏览器及 IDE 均启用 Source Map 支持，生产环境应设为 'hidden' 并上传至 Sentry。
css.sourcemap: true 是起点，不是终点
Vite 的 css.sourcemap 默认在开发环境为 true，但这个值容易被插件、环境变量或自定义 CSS 处理器（比如 lightningcss）覆盖。如果你改了 SCSS 文件却在 DevTools 的 Sources 面板里只看到编译后的 CSS，大概率是它被静默关掉了。
显式写死配置最稳妥：
export default defineConfig({<br> css: {<br> sourcemap: true<br> }<br>})
- 该配置仅影响 Vite 原生 CSS/SCSS/Less 处理链，不作用于通过
rollup-plugin-postcss等第三方插件接管的流程 - 若项目用了
lightningcss（Vite 5.0+ 默认启用），需额外确认它是否启用了 sourcemap：它默认关闭，需在css.transformer: 'lightningcss'下手动配lightningcss: { sourcemap: true } - 深嵌套
@use或虚拟模块导入（如@use 'virtual:design-tokens'）时，自定义 importer 必须透传sourceMap选项，否则映射断裂
浏览器和 IDE 必须手动开开关
即使 Vite 正确生成了 .css.map 文件，Chrome 和 WebStorm 也不会自动加载——它们默认禁用 CSS Source Map 支持。
- Chrome：打开 DevTools → ⚙️ Settings → Preferences → Sources → 勾选 Enable CSS source maps
- WebStorm：File Watcher 的 Arguments 必须含
--source-map，且 Output path 要匹配 Vite 输出路径（例如$ProjectFileDir$/dist/css/$FileNameWithoutExtension$.css） - 确保 HTML 中引入的是
.css文件（不是.scss），且该 CSS 文件末尾有/*# sourceMappingURL=xxx.css.map */注释（sourcemap: true模式下自动生成）
生产环境别裸发 .map 到 CDN
线上调试 ≠ 把 .css.map 直接扔到公网。一旦部署，攻击者打开 DevTools 就能下载完整 SCSS 结构、变量名、注释甚至内联图片路径。
立即学习“前端免费学习笔记（深入）”；
- 构建时设
css: { sourcemap: 'hidden' }→ 生成.css.map，但不加sourceMappingURL注释，浏览器不会加载 - 用 CI/CD 脚本提取
dist/**/*.css.map，通过 Sentry CLI 或私有 APM 上传，并绑定 release 版本号（如2026.10.02-v1） - 上传成功后立即执行
rm -f dist/**/*.css.map，确保产物目录里没有残留 - 验证：检查最终上线的 CSS 文件末尾是否**完全没有**
sourceMappingURL字样
常见错误现象与定位点
“明明开了 sourcemap 却看不到源码”——这类问题几乎都卡在中间某个环节断链，而不是配置本身。
- 现象：Sources 面板里只有
style.css，没展开出Button.scss等原始文件 → 检查 Chrome 是否启用了 CSS source maps - 现象：点击 CSS 规则跳转失败，显示 “No source available” → 查看 Network 面板，确认浏览器是否成功请求了
Button.scss（404 表示路径映射错，常见于@use别名或别名路径未被正确解析） - 现象：SCSS 报错行号对不上 → 检查是否用了
postcss-nested等插件，它们可能干扰 sourcemap 行列偏移；建议优先用原生@layer/@use - 现象：构建后 CSS 体积暴涨 →
sourcemap: 'inline'会把 base64 编码的 map 塞进 CSS 底部，仅限本地快速验证，严禁用于 build
真正麻烦的从来不是“怎么开”，而是“哪一环悄悄关了”。每次怀疑失效，先查浏览器控制台的 Network 标签页里有没有 404 的 .map 请求，再倒推 Vite 配置、插件链、浏览器设置三层。
