SCSS文件名必须带.module.scss后缀才启用CSS Modules模块化，否则即使配置modules:true也按全局样式处理；:global()是覆盖第三方库样式的唯一安全方式。
SCSS 文件名必须带 .module.scss 后缀才启用模块化
Webpack 的 css-loader 默认只对 .module.css 或 .module.scss 这类显式命名的文件启用 CSS Modules。如果你写的是 Button.scss，哪怕配置了 modules: true，它仍按全局样式处理——类名不会哈希，import styles from './Button.scss' 拿到的会是空对象或原始类名，冲突照旧。
常见错误现象：.btn 在多个组件里定义，结果所有按钮样式互相覆盖；调试时发现 DevTools 里类名还是 btn，没变成类似 Button_btn__xyz123 的哈希值。
- 务必重命名：把
styles.scss改成styles.module.scss - Webpack 配置中确保
scss规则也启用了modules: true，不能只配了.css规则 - 别依赖文件路径或注释“声明模块”，后缀是唯一触发开关
:global() 是唯一安全写第三方样式覆盖的方式
Material Components Web、Ant Design 这类库大量使用固定类名（如 mdc-button、ant-modal），你没法改它们的 HTML 结构，只能靠 CSS 覆盖。但直接在 .module.scss 里写 .mdc-button { color: red; } 会被哈希成无效选择器——浏览器根本找不到这个类。
正确做法是用 :global() 显式声明作用域外的样式：
立即学习“前端免费学习笔记（深入）”；
/* Button.module.scss */
:global(.mdc-button) {
font-weight: 600;
}
.button {
padding: 8px 16px;
}这样 .mdc-button 保持原样输出，而 .button 会被哈希隔离。漏掉 :global() 是大型项目里最常被忽略的“覆盖失效”原因。
-
:global()只能包裹选择器，不能包裹嵌套规则或变量 - 不要写
:global { .mdc-button { ... } }—— 语法错误，会编译失败 - 多个第三方类需分别包裹：
:global(.ant-input), :global(.ant-select)
SCSS 的 @import 不会破坏模块作用域
很多人担心 @import 'variables'; 或 @import 'mixins'; 会把全局样式“带进来”。其实不会：SCSS 的 @import 只是编译时内容拼接，不产生实际 CSS 输出；真正生成样式的是你当前 .module.scss 文件里写的规则。
也就是说，只要 variables.scss 里只有 $primary-color: #007bff; 这类定义，没有 .header { ... } 这样的选择器，它就不会引入任何类名冲突。
- 可放心复用颜色、断点、函数等抽象层，不影响模块隔离
- 若
base.scss里写了.reset { margin: 0; }，导入后它仍会被哈希（因为宿主文件是.module.scss） - 想导出全局重置？单独建
reset.css，用<link>引入，别走模块流程
哈希类名在 SSR 和 HMR 下依然稳定
比起 CSS-in-JS（如 styled-components），CSS Modules 的哈希是在构建时确定的，不依赖 JS 执行时机。这意味着：
- 服务端渲染时，
styles.button输出的类名和客户端完全一致，不会 FOUC - 热更新（HMR）替换样式文件，哈希值不变（只要文件路径和类名没变），DOM className 不会闪动或错位
- 同一份
Button.module.scss在不同构建环境（CI/CD、本地）生成的类名也一致，利于缓存和审查
容易被忽略的一点：如果你在 SCSS 中用了 #{} 动态插值（比如 .icon-#{$type}），这部分类名不会被哈希——它绕过了 CSS Modules 的解析逻辑，得手动加前缀或改用 CSS 变量。
