Sass 与 CSS Modules 可天然协同，因 loader 链中 sass-loader 先编译 Sass 语法（支持变量、嵌套、mixin），再由启用 modules 的 css-loader 对生成的 CSS 进行哈希隔离，文件名含 .module.scss 即自动触发该流程。
能直接协同，不需要“桥接”或额外 wrapper —— 只要文件名带 .module.scss，Webpack（或 Vite）就能自动启用 CSS Modules 并保留全部 Sass 功能。
为什么 .module.scss 文件天然支持 Sass 语法
CSS Modules 是 css-loader 的一个选项，它不关心源码是纯 CSS、SCSS 还是 Less；只要 loader 链中 css-loader 开启了 modules: true，且文件匹配 .module.scss 后缀，就会走模块化流程。Sass 编译（sass-loader）发生在 css-loader 之前，所以变量、嵌套、@mixin 全部可用，且作用域仍被哈希隔离。
- 错误认知：以为要先编译 Sass 再“塞进” CSS Modules —— 实际是 loader 链顺序决定的：sass-loader → css-loader（带 modules）→ style-loader
- 关键点：
css-loader的modules选项必须启用，且只对匹配.module.*的文件生效（这是默认约定，也可自定义正则） - 变量和 mixin 可跨文件复用，但注意：全局变量需通过
@use显式导入，不能靠@import拼接（后者已被 Sass 官方弃用，且易导致变量污染）
css-loader 的 localIdentName 怎么影响开发体验
类名哈希格式直接影响调试和可读性。默认生成如 Button_primary_3xK7b 这类名字，但你可以调整 localIdentName 参数来平衡唯一性与可读性。
- 开发期推荐：
[name]__[local]___[hash:base64:5]—— 文件名 + 原始类名 + 短哈希，既防冲突又方便定位 - 生产环境可加
[hash:base64:3]缩短长度，减少 bundle 体积 - 避免用
[path]或[folder]：路径过长会导致类名爆炸，且 Windows/macOS 路径分隔符不一致可能引发构建差异 - 不要关闭哈希（比如设为
[local]）：这等于退化成普通 CSS，失去模块化意义
如何在 .module.scss 中安全复用 Sass 变量和 mixin
不能依赖隐式全局注入。每个 .module.scss 文件都是独立作用域，必须显式导入所需逻辑。
立即学习“前端免费学习笔记（深入）”；
- 全局主题变量（如
$primary-color）应统一放在src/theme/variables.scss，然后在每个模块文件里写：@use "@/theme/variables" as *; - 公共 mixin（如
responsive-padding）建议单独抽成src/styles/mixins.scss，再用@use "@/styles/mixins" as mixins;导入后调用@include mixins.responsive-padding; - 禁止在
.module.scss里用@import引入其他 SCSS 文件：它会破坏模块边界，且无法 tree-shake，还可能触发重复定义警告 - Vite 用户注意：Vite 默认用
postcss-import处理@import，但该插件不支持@use，务必改用官方sass插件并确保@use语法正常解析
常见报错和对应解法
报错往往不是 Sass 或 CSS Modules 单独的问题，而是 loader 配置或语法混用导致的。
-
Module build failed: SassError: Undefined variable "$color-primary"→ 检查是否漏了@use，或路径写错（Vite 中别名@/需在vite.config.ts配置resolve.alias） -
Cannot find module './Button.module.scss' or its corresponding type declarations（TS 报错）→ 在src/react-app-env.d.ts或项目根目录global.d.ts中补充声明：declare module "*.module.scss" { const classes: Record<string string>; export default classes; }</string> - 样式没生效，但 DOM 上有 class 名 → 打开浏览器开发者工具，看元素上渲染的 class 是否真被插入到
<style>标签里；若没有，大概率是css-loader的modules选项没生效，或文件名不满足.module.scss规则 - 热更新失效（修改 SCSS 后页面不刷新）→ 确保
sass-loader和css-loader都开启sourceMap: true，且 HMR 插件（如react-refresh-webpack-plugin）兼容模块化样式
真正容易被忽略的是：Sass 的 @use 和 CSS Modules 的作用域是两层独立机制，前者管变量/mixin 可见性，后者管类名作用域。它们叠加时不会互相干扰，但也不会自动融合——你得亲手把变量导入每个需要它的 .module.scss 文件里，没有捷径。
