CSS Modules 依赖文件名以 .module.css 结尾并用 import styles from './X.module.css' 导入，否则为全局样式；动态拼接类名需防 undefined，:global() 仅限必要场景且内部不哈希。
直接用 import styles from './Component.module.css'，而不是 import './Component.module.css' —— 后者导入的是全局样式，前者才是局部作用域。
文件名必须带 .module.css 后缀
CSS Modules 不是靠配置开关启用的，而是构建工具（如 Vite、Webpack）按文件名约定自动识别。只有后缀为 .module.css 的文件才会被处理成模块化样式。
-
Button.module.css✅ 正确，类名会被哈希，作用域隔离 -
Button.css❌ 全局注入，无哈希，易冲突 -
Button.modules.css❌ 拼写错误，等同于普通 CSS 文件 -
Button.module.scss✅ 支持，但需确保已配好sass-loader或对应预处理器
导入方式必须解构为命名对象
不能只引入、不接收导出对象；也不能用 import * as styles（在 CRA 中会返回空对象）。
- ✅ 正确：
import styles from './Button.module.css'，然后className={styles.btn} - ❌ 错误：
import './Button.module.css'—— 样式生效但类名未哈希，全局污染 - ❌ 错误：
import * as styles from './Button.module.css'—— 多数构建环境返回空对象，styles.btn为undefined
动态拼接类名时要防 undefined
styles 是普通 JS 对象，键不存在时取值为 undefined。直接字符串拼接会导致 className="btn undefined"，React 渲染后变成 className="undefined"，样式彻底丢失且无报错提示。
立即学习“前端免费学习笔记（深入）”；
- ❌ 危险写法：
className={`${styles.btn} ${styles.primary}`} - ✅ 推荐写法：
className={clsx(styles.btn, styles.primary)}（用clsx自动过滤 falsy 值） - ✅ 或手动防护：
className={[styles.btn, props.primary && styles.primary].filter(Boolean).join(' ')}
:global() 不是“绕过模块化”的快捷方式
:global() 是显式逃逸机制，仅用于必要场景（如重置第三方组件样式、对接遗留 CSS），不是补救类名写错或结构混乱的兜底方案。
- ✅ 合法：
:global(.ant-btn) { margin: 0; }或.container :global(.icon) { color: blue; } - ❌ 非法：
.btn { :global(.icon) { ... } }—— 嵌套语法不被解析，编译后无效 - ⚠️ 注意：
:global()内部的选择器不会哈希，等同于写全局 CSS，滥用等于放弃模块化收益
最常被忽略的点：文件名拼错或导入方式不对，都不会报错，样式照常生效——只是悄悄变成了全局污染。开发时建议加一句 console.log(styles) 确认对象里真有预期的键值对。
