React中CSS Modules的类名映射依赖文件名与Block名严格一致，如Button组件必须命名为Button.module.css，否则styles对象无法正确映射类名，导致样式静默失效且不报错。
文件名必须与Block名完全一致，否则styles对象里查不到类
React中CSS Modules的类名映射依赖文件名作为Block根。比如Button组件，CSS文件必须命名为Button.module.css，里面写.button、.button__icon、.button--primary；JSX中才能用styles.button或styles['button__icon']安全访问。一旦文件名是button.module.css（小写）或MyButton.module.css（不匹配组件名），styles.button__icon就返回undefined，控制台不报错，但样式静默失效。
验证方法很简单：console.log(styles)看输出里有没有你要的键；再打开浏览器开发者工具，检查编译后生成的CSS文件，确认类名前缀是不是Button__开头（不是button__或MyButton__）。
常见踩坑点：
- 文件名含大写字母但JSX里用小写访问：
Button.module.css→styles['button__icon']（错） - CSS里写了
.btn__icon，但文件名是Button.module.css→styles['btn__icon']始终为undefined - 路径中含空格或中文，导致Webpack解析失败，styles为空对象
别手写字符串拼类名，用bem工厂+classnames组合
写className={`button ${isActive ? 'button--active' : ''} ${hasIcon ? 'button__icon' : ''}`}看似简单，实则埋了三个雷：空格漏写、连字符写成单横线（button-active）、传入null或undefined导致多余空格。更严重的是，它绕过CSS Modules的哈希校验——拼错类名，样式就直接消失，还不报错。
立即学习“前端免费学习笔记（深入）”；
正确做法是封装一个绑定Block名的生成器：
const bem = (block) => ({
e: (el) => `${block}__${el}`,
m: (mod) => `${block}--${mod}`
});
const buttonBem = bem('button');
再配合classnames使用：
import cn from 'classnames';
className={cn(
styles.button,
buttonBem.m('primary'),
{ [buttonBem.e('icon')]: hasIcon },
{ [styles['button--loading']]: isLoading }
)}
关键约束：
- 所有Element和Modifier都必须通过
buttonBem.e()或buttonBem.m()生成，禁止硬编码字符串如'button__icon' - 修饰符值必须受控，避免
buttonBem.m(theme)这种写法，theme应来自枚举或类型守卫 - 不要解构
styles后直接拼：${styles.button} ${styles['button--primary']}—— 后者若不存在，会拼出undefined
Modifier只能挂Block或Element上，不能嵌套或跨级
BEM的--修饰符必须与Block或Element并列，不能挂在子元素上。比如button__icon--large是反模式，语义混乱且Sass编译易出错；正确写法是button__icon button__icon--large，两个独立类名。
常见错误场景：
-
button--primary__icon：语法非法，CSS解析失败 -
card__header--expanded：header的状态应由card--expanded统一控制，否则header变高时，card其他部分布局可能断裂 -
dialog__body--large：尺寸是整个dialog的状态，应写成dialog--large，否则padding、font-size等无法协调
修饰符命名本身也有强约束：--loading可接受，--blue不行（绑定视觉值）；--size-large比--large更啰嗦，BEM推荐原子化短名，只要能被JS安全切换（el.classList.toggle('dialog--large')）即可。
开发期必须开启localIdentName调试模式
默认的CSS Modules哈希类名（如Button_button__abc123）对调试极不友好。开发时务必在css-loader或Vite配置中设置localIdentName=[name]__[local]___[hash:base64:5]，让生成的类名变成Button_button___abc12这类可读格式。
这样做的实际好处：
- 浏览器审查元素时，一眼看出样式来自哪个文件、哪个类名
- 遇到
undefined类名，立刻反查CSS文件里是否真有对应声明 - 配合
postcss-bem-linter做构建时校验，能捕获.card和.button混写、__嵌套等结构错误
注意：这个配置只应在开发环境启用，生产环境仍用默认哈希，避免泄露源码结构。
