CSS Modules 靠文件命名（如 .module.css）和构建配置激活，非规范命名或 loader 未启用 modules: true 会导致 import styles 返回空对象；Webpack 仅匹配 /.module\.(css|sass|scss)$/，Vite 开箱支持但 .module.sass 需手动配置。
CSS Modules 不是“引入”出来的，而是靠文件命名 + 构建配置激活的——没按规则命名或 loader 没配对，import styles from './X.module.css' 就会得到一个空对象。
文件名必须带 .module.css（或对应预处理器后缀）
Webpack 的 css-loader 只有在匹配到 .module.css、.module.scss 这类后缀时，才会启用模块化逻辑。写成 Button.css 或 Button.module.less（未配置 less-loader 支持模块）都会失效。
常见错误现象：styles.button 是 undefined，控制台无报错，但元素没样式。
- ✅ 正确命名：
Button.module.css、Modal.module.scss - ❌ 错误命名：
Button.css、Button.modules.css（多了一个 s）、button.Module.css（大小写敏感，尤其 macOS/Linux） - Vite 用户注意：
.module.sass默认不支持，需手动加css.modules.localIdentName配置
css-loader 必须开启 modules: true
Webpack 项目里，如果用的是自定义配置（非 CRA/Vite），漏掉 modules: true 或写错位置，CSS Modules 就不会生效。CRA 从 v5 起默认支持，但仅限 .module.css；Vite 开箱即用，无需额外配置。
立即学习“前端免费学习笔记（深入）”；
将 React 应用升级到最新版本，从类组件迁移到 Hooks，并采用并发特性。用于现代化改造 React 代码库、迁移到 React Hooks 或升级到最新
关键配置示例（Webpack）：
{
test: /\.module\.(css|sass|scss)$/,
use: [
'style-loader',
{
loader: 'css-loader',
options: {
modules: {
localIdentName: '[name]__[local]--[hash:base64:5]'
}
}
},
'sass-loader'
]
}
-
localIdentName建议开发期保留[name]和[local]，方便调试时一眼看出来源 - 不要把
modules: true写在全局/\.css$/规则里——否则所有 CSS 都被模块化，第三方库样式会崩 - 想混用全局样式？单独配一条规则，比如
/\.global\.css$/，且不启用modules
动态拼接 className 时别绕过 styles 对象
写 className={`btn ${styles.primary}`} 没问题，但写 className={'btn ' + styles.primary} 或更糟的 className='btn ' + someCondition && styles.primary，容易因空值或布尔值转字符串导致 class 名变成 btn true 这种无效值。
- 推荐用
clsx或classnames库统一处理：className={clsx('btn', styles.primary, someCondition && styles.active)} - 避免直接拼
styles.xxx到字符串里——它可能为undefined，且无法被构建工具做静态分析 - 嵌套选择器（如
.container .item）在模块化后失效，改用:hover伪类或composes复用
:global() 是唯一安全的穿透方式
需要覆盖第三方组件（如 react-modal、react-diagrams）的样式，或者写 CSS 动画 keyframes 时，不能靠外层加 wrapper 类去强行提高权重，必须用 :global() 显式声明。
错误写法：.ReactModal__Overlay { background: rgba(0,0,0,0.8); } → 编译后变成 Modal__ReactModal__Overlay___xxx，根本匹配不到目标元素。
- ✅ 正确穿透：
:global(.ReactModal__Overlay) { background: rgba(0,0,0,0.8); } - ✅ 动画也得包住：
@keyframes :global(slideIn) { from { opacity: 0; } } - ⚠️ 注意：
:global()里的选择器仍是全局的，别滥用，否则就退回污染老路
最常被忽略的一点：CSS Modules 的作用域隔离只发生在编译时，它不改变 React 渲染逻辑，也不干预 DOM 结构。真正出问题的地方，往往不是“怎么写”，而是“文件没命对”或“loader 配错范围”。检查 styles 对象是否为空，比调样式优先级更快定位根因。
