CSS Modules默认类名与BEM不兼容，因其自动哈希（如.button→_button_1a2b3）破坏BEM可预测的命名结构；正确做法是保留源码中Button__icon--large等语义化类名，由CSS Modules在构建时哈希底层实现，同时严格遵循文件名、类名、JSX访问三者映射一致。
为什么CSS Modules默认类名和BEM不兼容
CSS Modules会自动哈希类名，比如 .button 编译后变成 _button_1a2b3，而BEM要求显式书写 Button__icon--large 这类可预测的命名。直接在JSX里写哈希后的类名不可能，也不该手动拼接——这破坏BEM的语义性和可维护性。
关键不是“禁用CSS Modules哈希”，而是让哈希只作用于底层实现，同时保留BEM命名在源码中可读、可推导。
- 别用
export const button = styles.button再传给组件——这绕过BEM结构，失去修饰符（--disabled）和元素（__text）的层级关系 - 别在CSS里写嵌套选择器模拟BEM（如
.Button .Button__text）——CSS Modules不支持真正嵌套，且违背BEM“扁平化”的初衷 - 必须让每个BEM块对应一个CSS Modules文件，且文件名与块名一致（如
Button.module.css），否则无法建立命名映射
如何正确导出并使用BEM类名
在 Button.module.css 中按BEM规范写类名，但不加任何前缀或嵌套：
.Button { }
.Button__icon { }
.Button--primary { }
.Button--disabled { }然后在组件中用解构方式导入，保持命名空间清晰：
立即学习“前端免费学习笔记（深入）”；
import styles from './Button.module.css';
<p>function Button({ variant, children }) {
return (
<button className={<code> ${styles.Button} ${variant === 'primary' ? styles['Button--primary'] : ''} ${props.disabled ? styles['Button--disabled'] : ''} </code>.trim()}>
<span className={styles['Button<strong>icon']} />
<span className={styles['Button</strong>text']}>{children}</span></p></button>
);
}- 所有BEM修饰符（
--xxx）和元素（__xxx）都必须用方括号语法访问，因为连字符在JS中不是合法标识符 - 不要合并多个BEM块到一个CSS文件（比如把
Input和Button都写进shared.module.css）——这会让类名失去块级作用域，也违反BEM“块即独立单元”原则 - 如果需要动态组合（如
Button Button--primary Button--small），推荐用clsx库，而不是手拼字符串
如何处理BEM嵌套场景（比如 Card__header__title）
BEM官方不鼓励三层嵌套（Block__element__subelement），Next.js 14里更不该这么干——CSS Modules本身不支持子选择器穿透，强行写会导致样式失效或意外全局污染。
正确做法是降级为两个独立块：
.Card { }
.Card__header { }
.CardHeader { } /* 新块 */
.CardHeader__title { } /* 元素属于CardHeader，不是Card */-
CardHeader应该是一个独立组件，有自己的CardHeader.module.css - 如果只是视觉分组，用
data-*属性或CSS自定义属性（--card-header-title-color）替代深层嵌套 - 绝对不要在JSX里写
className={styles['Card__header__title']}——这种类名根本不会被CSS Modules生成，运行时是undefined
开发体验优化：避免每次都要写 styles['xxx']
重复写方括号很烦，但不能靠 Object.keys(styles).forEach 动态挂载——这会破坏构建时的静态分析，导致HMR失效或服务端渲染类名不匹配。
- 可以用一个极简工具函数封装，例如：
const bem = (block, element, modifier) => { if (element) return styles[`${block}__${element}`]; if (modifier) return styles[`${block}--${modifier}`]; return styles[block]; };然后在组件里调用bem('Button', 'icon')或bem('Button', null, 'primary') - VS Code插件
CSS Modules IntelliSense能补全styles['Button__xxx']，比手敲安全 - TypeScript用户可在
Button.module.css.d.ts中手动声明模块类型，让TS校验BEM类名是否存在
最易被忽略的是：BEM类名的变更（比如从 Button__label 改成 Button__text）必须同步更新所有JSX中的字符串字面量——没有编译期检查，全靠人肉核对。这就是为什么建议搭配 eslint-plugin-css-modules + 自定义规则做字符串字面量校验。
