CSS Modules通过构建时将.button编译为Button_button__Kx2f1等唯一类名消除样式冲突，需严格满足文件后缀（.module.css）、路径正确、构建配置启用三条件，且必须用className={styles.button}引用，不可字符串拼接或写死类名。
因为 CSS Modules 能在构建时把 .button 这种类名编译成类似 Button_button__Kx2f1 的唯一值，样式冲突从物理层面被消除——只要后缀、路径、配置三者全对，就不可能污染其他组件。
文件后缀写错是第一大坑
CRA、Vite、Next.js 等现代脚手架只对 .module.css（或 .module.scss、.module.less）这类文件启用模块化。写成 Button.css 或 Button.modules.css 都无效。
-
import styles from './Button.module.css'✅ -
import './Button.css'❌（全局污染） -
import styles from './Button.module.scss'✅（但需确保已配 Sass loader）
className={styles.xxx} 是唯一合法用法
模块导出的是 JS 对象，不是字符串模板，也不支持运行时拼接。浏览器里看到 class="button" 就说明根本没走模块流程。
- ✅ 正确：
<button className={styles.button}> - ❌ 错误：
<button className="button">（绕过 modules） - ❌ 错误：
className={styles['btn-' + type]}（TS 不报错，但 runtime 为undefined） - 需要条件组合？用
clsx：className={clsx(styles.button, props.primary && styles.primary)}
:global() 不是逃生舱，是双刃剑
它能让你“逃出”模块作用域，但一旦滥用，就等于亲手拆掉隔离墙。
立即学习“前端免费学习笔记（深入）”；
- ✅ 合理场景：
:global(.ant-modal) { z-index: 9999; }（覆盖第三方库） - ✅ 合理场景：
:global(*) { box-sizing: border-box; }（基础重置） - ❌ 危险操作：把整个组件样式包进
:global()；用它去“修复”父组件没导出的类名 - ⚠️ 注意：
@import './reset.css'进模块文件，等价于写:global()，不是安全引入
最常被忽略的一点：CSS Modules 不报错，只安静返回 undefined。DevTools 里看到空 class 或 undefined 字符串，八成是 styles.xxx 查不到——这时候别猜，直接查文件后缀、路径大小写、CSS 里是否真定义了那个类名。
