CSS Modules通过构建时哈希类名实现物理级样式隔离，需严格匹配文件后缀（如.module.css）、正确导入对象并用styles.xxx访问，禁用@import和滥用:global()，否则将导致样式失效或全局污染。
因为 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）
:global() 不是逃生舱，是双刃剑
它能让你“逃出”模块作用域，但一旦滥用，就等于亲手拆掉隔离墙。
立即学习“前端免费学习笔记（深入）”；
- ✅ 合理场景：
:global(.ant-modal) { z-index: 9999; }（覆盖第三方库） - ✅ 合理场景：
:global(*) { box-sizing: border-box; }（基础重置） - ❌ 危险操作：把整个组件样式包进
:global()；用它去“修复”父组件没导出的类名
@import 在模块化工程中早已被弃用
@import 看起来更“纯 CSS”，但它实际带来三重问题：
- 加载阻塞：浏览器串行解析，每个都可能触发新请求，拖慢首屏渲染
- 无法参与构建：Webpack/Vite 无法识别路径依赖，导致 HMR 失效、Tree Shaking 失效
- 作用域为零：导入的样式仍是全局污染，完全违背模块化目标
替代方案明确：预处理器用 @use（Sass）或 @forward，JS 端统一用 import——更可控、可调试、可拆分。
最常被忽略的一点：CSS Modules 不报错，只安静返回 undefined。DevTools 里看到空 class 或 undefined 字符串，八成是 styles.xxx 查不到——这时候别猜，直接查文件后缀、路径大小写、CSS 里是否真定义了那个类名。
