CSS Modules 必须用 .module.css 命名并 import styles from './X.module.css'，否则静默退化为全局样式；动态拼接类名或嵌套 :global() 均非法。
文件名必须带 .module.css 后缀
CSS Modules 不是开关选项，而是构建工具（如 Vite、CRA、Webpack）按文件名正则 /\.module\.(css|scss|sass|less|styl)$/ 触发的机制。命名不匹配，样式就静默退化为全局注入，且控制台零报错。
常见错误现象：Button.css 里写了 .btn，组件中用 className={styles.btn} 却始终是 undefined——因为没启用模块化，styles 对象根本为空。
-
Button.module.css✅ 正确，被识别为模块 -
Button.modules.css❌ 拼写错误，等同于Button.css -
Header.module.scss✅ 支持，但需确保已配sass-loader或对应预处理器 loader -
index.module.less✅ 同理，依赖less-loader
导入必须写成 import styles from './X.module.css'
这是最常踩的坑：用 import './X.module.css' 看似省事，实际只做了全局样式注入，类名不哈希，所有组件共享原始类名，等于完全没开 CSS Modules。
更隐蔽的错误是 import * as styles from './X.module.css'——在 CRA 中返回空对象，styles.btn 一定是 undefined。
立即学习“前端免费学习笔记（深入）”；
- ✅ 正确：
import styles from './Button.module.css'，然后className={styles.btn} - ❌ 错误：
import './Button.module.css'（全局注入） - ❌ 错误：
import * as styles from './Button.module.css'（CRA 下为空对象） - ⚠️ 注意：
styles是普通 JS 对象，键是原始类名，值是哈希字符串（如Button_btn__kx9f2），不能当字符串直接拼接
动态类名拼接必须预定义，不能运行时构造
CSS Modules 的 styles 对象是编译期静态生成的，运行时不存在“按需生成类名”的能力。试图用 JS 动态拼出类名，必然失败。
常见错误现象：元素渲染后 className 是空字符串或 undefined，DevTools 里看不到样式生效。
- ❌ 危险：
className={`${styles.btn} ${styles['btn--' + size]}`—— 若btn--large没在.module.css文件里显式声明，styles['btn--large']就是undefined - ✅ 正确：
className={clsx(styles.btn, size === 'large' && styles['btn--large'])} - ✅ 更稳妥：
className={clsx(styles.btn, size === 'large' ? styles['btn--large'] : null)} - ? 提示：所有要用到的变体类（如
.btn--primary、.btn--disabled）必须提前写死在.module.css文件中
:global() 只能用于顶层或后代选择器，不能嵌套
:global() 是逃生舱，不是后门。滥用会破坏模块边界，让 CSS Modules 形同虚设。
常见错误现象：写了 .container { :global(.icon) { color: blue; } }，但编译后该规则完全消失——CSS Modules 解析器不支持这种嵌套语法。
- ✅ 合法：
:global(.ant-btn) { margin: 0; }（顶层穿透） - ✅ 合法：
.container :global(.icon) { color: blue; }（作为后代选择器的一部分） - ❌ 非法：
.container { :global(.icon) { } }（嵌套在局部规则块内，不被解析） - ⚠️ 注意：
:global()内部的选择器不会被哈希，会原样输出到 DOM，务必确认它真的需要全局作用域
真正容易被忽略的是：模块化失效往往没有报错，只是样式“看起来没起作用”。查不到问题时，先看三件事——文件名对不对、导入写法对不对、用到的类名有没有在 CSS 文件里明确定义过。这三处任一出错，CSS Modules 就彻底退出了。
