CSS Modules文件名必须与BEM块名严格对齐，类名映射依赖文件名作为Block根，如Button.module.css中.btn解析为Button_btn__abc123；块名需语义一致、元素用双下划线、修饰符须与Block同级；classnames可安全拼接BEM类名；postcss-bem-linter是BEM落地的校验底线；localIdentName应保留[name]和[local]以利调试。
React中CSS Modules文件名和BEM块名必须严格对齐
CSS Modules的类名映射依赖文件名作为Block根，比如Button.module.css里定义的.btn会被解析为Button_btn__abc123，但如果你在JSX里写className={styles['button']}（少了个n），就拿不到样式——因为button根本没在CSS里声明。
常见错误现象：styles.button返回undefined，控制台无报错，但样式不生效；或误用styles['btn__icon']却忘了在CSS里写.btn__icon，只写了.btn-icon。
- 块名（Block）必须与文件名语义一致：
Card.module.css→ 所有类名以.card开头，不能出现.product-card或.ui-card - Element必须用双下划线：
.card__header合法，.card-header会被当作普通类，失去BEM结构约束 - Modifier必须与Block同级：
.card--loading可直接用于根节点，.card__content--loading是反模式，应拆成.card__content+ 独立状态类或用JS控制显示
classnames动态拼接BEM类名时，别手动拼字符串
用classnames不是为了“看起来高级”，而是避免空格、重复、漏false值。手动写{`card ${isHovered ? 'card--hovered' : ''} ${hasShadow ? 'card--shadow' : ''}`}容易多空格、逻辑错位，且无法自动过滤null/undefined。
正确做法是把BEM结构封装成函数，再交给classnames合并：
立即学习“前端免费学习笔记（深入）”；
import cn from 'classnames';
const bem = (block) => {
const e = (el) => `${block}__${el}`;
const m = (mod) => `${block}--${mod}`;
return { e, m };
};
const b = bem('card');
// 使用
<div className={cn(b.m('loading'), b.e('header'))} />
- 不推荐直接解构
styles后拼接：${styles.card} ${isDark && styles['card--dark']}——当isDark为false时会留下多余空格 -
classnames会自动忽略falsy值，所以cn(styles.card, isDark && styles['card--dark'])比三元更安全 - 修饰符字段要收敛：不要暴露
card--size-large--theme-dark--state-disabled这种长串，统一用size="large"、theme="dark"等props控制
postcss-bem-linter不是可选插件，是BEM落地的校验底线
没有linter，BEM在团队协作中三个月内就会退化：有人写.btn__icon--primary，有人写.btn-icon-primary，还有人把user-card__btn塞进Header.module.css——这些错误不会报错，但会让BEM失去语义自治能力。
配置postcss-bem-linter后，它会立刻报出以下问题：
-
.header-btn→ 错误：非当前Block前缀（期望.header） -
.btn--icon→ 错误：修饰符不应描述结构（--icon应为__icon） -
.card__footer__copyright→ 错误：不允许三层嵌套（BEM只允许Block__Element或Block--Modifier）
它不阻止你写错，但能让你在保存文件时立刻看到红标——比Code Review早十轮。
CSS Modules的localIdentName别设成[hash]
构建时用[hash]生成类名（如_abc123）看似压缩，实则让调试变成噩梦：你在浏览器里看到div class="_x7y9z"，完全无法对应到Card.module.css里的哪一行。而[name]__[local]--[hash:base64:5]生成Card_card--loading--aBc12，既保留语义又足够短。
- 开发环境建议关闭哈希：
modules: { localIdentName: '[name]__[local]' }，所见即所得 - 生产环境启用哈希，但必须保留
[name]和[local]，否则CI构建后无法定位样式来源 - 禁用
getLocalIdent自定义函数——除非你真需要按目录分组（如components-Card_card），否则徒增复杂度
BEM真正的难点不在语法，而在所有人对“什么该是Block、什么该是Modifier”的理解是否一致。一个按钮组件要不要把size做成Modifier（btn--large）还是用内联style控制，这种决策比写对__和--重要得多。
