CSS Modules 必须用 .module.css 后缀命名文件、import styles from './X.module.css' 解构导入、className={styles.xxx} 动态绑定，三者缺一不可；否则静默退化为全局样式，导致类名覆盖。
CSS Modules 是 React 中真正能解决样式冲突的方案，不是“优雅”可选，而是工程必需。 普通 import './Button.css' 看似简单，但只要项目超过两个组件，.btn、.container 这类通用类名就会互相覆盖，且控制台零报错——你只能靠肉眼排查 UI 错乱。
为什么 import './Button.css' 会静默污染全局？
Webpack 的 css-loader + style-loader 默认把所有 CSS 当作全局资源处理。哪怕你只在 Button.js 里 import './Button.css'，它生成的样式规则也会注入 ，对整个页面生效。
- 多个组件同时引入
header.css和modal.css，若都含.title，后加载的会覆盖前者的颜色/字体 - 构建产物中看不到警告或错误，DevTools 里只能看到一堆重复的
.title规则，顺序难追溯 - CI/CD 构建顺序微调（如文件遍历顺序变化）就可能导致线上样式随机错乱
如何正确启用 CSS Modules？三步缺一不可
它不是开关配置，而是构建工具按文件名和导入方式联合触发的机制。漏掉任意一环，就退化为普通全局 CSS。
- 文件名必须带
.module.css后缀：Button.module.css✅，Button.css❌，Button.modules.css❌（拼写错误） - 导入必须解构为对象：
import styles from './Button.module.css'✅，import './Button.module.css'❌（类名不哈希），import * as styles from './Button.module.css'❌（CRA 中返回空对象） - 使用必须通过对象属性：
className={styles.btn}✅，不能写成className="btn"或字符串拼接{`${styles.btn} ${styles.primary}`}（后者若styles.primary不存在，会得到"btn__abc undefined"）
全局样式和模块样式能共存吗？能，但必须分层明确
它们根本不在同一作用域，不是“混用”，而是职责分离：
立即学习“前端免费学习笔记（深入）”；
-
import './base.css'：只放重置样式、CSS 变量（:root）、工具类（如.sr-only）、字体定义——它本就应该全局生效 -
import styles from './Button.module.css'：只描述 Button 组件内部结构，类名哈希后天然隔离，base.css里的.btn对它完全无影响 - 禁止在
.module.css文件里@import './base.css'——这会破坏模块边界，且多数构建工具不支持
动态类名和 TypeScript 下容易忽略的坑
styles 是运行时 JS 对象，键是原始类名，值是哈希后的字符串（如 Button_btn__kx9f2）。它不参与编译期类型检查，也无自动补全。
- 开发时建议加
console.log(styles)确认导出内容；VS Code 安装CSS Modules IntelliSense插件可补全类名 - TypeScript 项目需手动声明模块类型，否则
styles.xxx会报Property 'xxx' does not exist on type '{...}' - 用
clsx拼接类名比手写模板字符串更安全：className={clsx(styles.btn, props.primary && styles.primary)}，避免undefined污染
最常被跳过的环节是文件名后缀和导入写法——这两个地方出错，CSS Modules 就彻底失效，而你根本收不到任何提示。别指望“看起来一样就行”，构建工具只认字面匹配。
