css modules是构建时类名哈希化机制，需严格匹配文件名（如button.module.css）和导入方式（import styles from './x.module.css'），否则静默失效。
CSS Modules 不是“开启开关”，而是靠文件名和导入方式共同触发的构建时机制；用错命名或错用 import，样式就静默失效，且不报错。
文件名必须带 .module.css（或 .module.scss）后缀
Webpack/Vite 等工具只认这个约定，不是配置项可开关。命名不匹配，就当普通 CSS 处理：
-
Button.module.css✅ 被识别为模块，类名哈希化 -
Button.css❌ 全局注入，所有组件共享.button -
Button.modules.css❌ 拼写错误，等同于.css -
Header.module.scss✅ 支持，但需确保已配sass-loader
create-react-app 默认支持，Vite 需确认 css.modules 配置未被覆盖。
导入必须写成 import styles from './X.module.css'
不能写成 import './X.module.css' 或 import * as styles from './X.module.css'：
-
import styles from './Button.module.css'✅ 返回对象：{ btn: 'Button_btn__kx9f2', primary: 'Button_primary__3aLmN' } -
import './Button.module.css'❌ 样式生效，但类名不哈希，等于没模块化 -
import * as styles from './Button.module.css'❌ CRA 中返回空对象，styles.btn是undefined
动态拼接类名时，className={`${styles.btn} ${styles.primary}`} 有风险——若 styles.primary 不存在，结果含 "undefined"，样式丢失无提示。建议用 clsx(styles.btn, styles.primary) 或三元判断。
:global() 只能用于顶层或后代选择器，不能嵌套
它不是“绕过模块”的万能钥匙，而是受严格语法限制的逃生舱：
-
:global(.reset-button)✅ 合法，输出真实类名 -
.container :global(.icon)✅ 合法，作为后代选择器 -
.container { :global(.icon) { ... } }❌ 语法错误，构建失败
滥用 :global() 会让模块化形同虚设。需要穿透时，优先考虑抽离为 base.css（如重置、字体、工具类），单独全局引入。
HMR 失效时 className={styles.xxx} 变成 undefined 的常见原因
这不是 React bug，是哈希类名生成依赖导入顺序和静态分析，热更新无法同步变更：
- 调整了同一文件中多个
.module.css的import顺序 - 条件导入，比如
process.env.NODE_ENV === 'development' && import('./Debug.module.css') - 混用
import styles from './A.module.css'和import './B.css'，后者干扰哈希计算
临时解法是手动刷新；长期应锁定导入顺序、避免动态导入样式模块、把基础样式抽到非模块化文件中。
最易被忽略的一点：CSS Modules 的“私有”只作用于类名，不自动隔离变量、@keyframes 或 :root 定义。如果用了 SCSS 变量，记得加下划线前缀（如 --_internal-color）表明内部使用，避免意外泄漏到全局作用域。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
