上线后CSS与本地不一致，根本原因是构建环境差异：CI/CD缺失sass、混装node-sass、sourceMap未关闭、@import干扰@use、路径别名未透传或文件权限异常，须逐层对齐编译链路。
上线后 CSS 和本地编译结果不一致，基本可以断定是构建环境差异导致的——不是代码写错了，而是编译链路在 CI/CD 或生产服务器上悄悄变了。
CI/CD 环境缺失 sass 或混装 node-sass
本地能跑，上线报 @use 语法错误或 Module not found，大概率是构建机没装 sass，或者同时装了 node-sass 和 sass，导致 sass-loader 随机挑一个用。
- 执行
npm ls sass和npm ls node-sass—— 必须只存在sass（Dart Sass），node-sass必须完全卸载 - CI 脚本里加检查：
node -p "require('sass').info"，确保加载的是 Dart Sass（输出含dart-sass字样） - Webpack 配置中删掉所有
implementation: require('node-sass')，让它自动找sass - 某些旧版
sass-loader@12在 Node 20+ 下会 fallback 到node-sass，必须升到@13.3.0+
构建时未启用 sourceMap: false 导致压缩逻辑错乱
本地开发开 sourcemap 没问题，但上线若漏关，sass-loader 会把 map 内容塞进 CSS 底部，而后续 cssnano 或 MiniCssExtractPlugin 可能误处理它，造成样式顺序错位、注释残留甚至选择器被截断。
-
sassOptions中显式设sourceMap: false（别依赖默认值，不同版本默认不同） - 确认
css-loader和postcss-loader的sourceMap也关了，避免多层 map 叠加污染 - 上线前用
grep -n "sourceMappingURL" dist/main.css快速验证是否还有 map 引用
@use 被静默降级为 @import 模式
上线后变量失效、mixin 找不到、CSS 输出体积暴增——这往往是因为某处 @import 把整个文件拖回 legacy 模式，@use 全部失效，但本地可能因缓存没暴露问题。
立即学习“前端免费学习笔记（深入）”；
- 全局搜索
@import，尤其注意@import 'xxx.css'这种非法用法（CSS 文件不该被@import进 SCSS） - 确认所有
@use语句都在文件第一行非注释位置，前面不能有空行、BOM 或 UTF-8 签名 - 被
@use的文件名必须以下划线开头（如_variables.scss），且路径不能带.scss后缀 - CI 构建前加校验脚本：
grep -r "@import" src/styles/ | grep -v "node_modules"，发现就中断发布
路径别名在 CI 中解析失败
本地 @use '@/styles/vars' 没问题，上线却报 Can't find stylesheet，常见于 Vite 或 Webpack 的 alias 配置没透传给 sass 解析器。
- Vite 用户：必须在
vite.config.js中显式配sassOptions: { loadPaths: ['./src/styles'] }，仅靠resolve.alias不生效 - Webpack 用户：在
sass-loader的options.sassOptions里加loadPaths: [path.resolve(__dirname, 'src/styles')] - 别用
~或@别名直接写进@use路径里——sass本身不认识这些，得靠loadPaths或importer插件支持 - CI 日志里加
ls -la src/styles/_vars.scss，确认文件确实存在且权限可读
真正麻烦的从来不是“为什么不一致”，而是“哪一层悄悄变了”——Sass 编译链路上每个环节（loader、implementation、alias、sourcemap、甚至 @import 的存在）都可能成为单点故障，上线前必须逐层对齐本地与 CI 的实际执行路径。
