styles.button__icon报undefined的根本原因是文件名、类名、JSX访问三者未对齐：文件必须为Button.module.css（PascalCase），CSS中需定义.button__icon，JSX中须用styles['button__icon']访问。
直接用 styles.button__icon 会报 undefined，不是 BEM 写错了，而是文件名、类名、JSX 访问三者没对齐——这是 Next.js 14 中 CSS Modules + BEM 最常卡住的地方。
为什么 styles.button__icon 总是 undefined
CSS Modules 的哈希前缀由文件名决定，不是类名。比如文件叫 Button.module.css，它生成的映射键只包含你在该文件里明确定义的、以 .button 开头的类（如 .button、.button__icon、.button--primary）。
- 文件名必须是
Button.module.css（PascalCase，与组件名完全一致），不能是button.module.css或MyButton.module.css - CSS 文件里必须写
.button__icon { }，不能写.btn__icon、.Button__icon或.button-icon - JSX 中必须用字符串访问：
styles['button__icon']✅，styles.button__icon❌（语法错误），styles['Button__icon']❌（大小写不匹配） - 验证方式：在组件里
console.log(styles)，看输出对象里有没有button__icon这个 key；再查 DevTools 里最终 class 名是否以Button_button__开头
如何在 Button.module.css 中安全写 BEM 类名
别把 BEM 当成“多写几个下划线”，它是工具链识别结构的语法锚点。CSS 文件本身要能被 postcss-bem-linter 校验通过，否则构建时就埋了坑。
- 只允许出现以
.button开头的类：.button、.button__icon、.button--primary—— 其他都算越界 - 禁止嵌套选择器：
.button .button__text是反模式，CSS Modules 不支持真嵌套，也违背 BEM 扁平原则 - 用注释分区提升可读性：
/* === BLOCK: button === */、/* === ELEMENTS === */、/* === MODIFIERS === */，空行分隔，方便 VS Code 折叠和搜索 - Element 和 Modifier 必须严格分离：
.button__icon--large是错的，应拆成.button__icon+.button__icon--large或改用.button--large
动态拼接类名时怎么避免手拼字符串
写 {`button ${isActive ? 'button--active' : ''}`} 看似省事，实则绕过 CSS Modules 作用域，导致样式静默失效、TypeScript 无法校验、空格控制不可靠。
使用 JSON Schema 验证 JSON 数据，从示例 JSON 生成 schema，并将其转换为 TypeScript 接口、Python 数据类或 Markdown 文档。
立即学习“前端免费学习笔记（深入）”；
- 所有类名必须来自
styles对象，哪怕只是修饰符：styles['button--primary']、styles['button__icon'] - 用
clsx处理条件逻辑：clsx(styles.button, { [styles['button--primary']]: variant === 'primary' }) - 封装 BEM 工厂函数绑定 block 名：
const b = bem('button')，然后styles[b.e('icon')]或styles[b.m('disabled')]，避免硬编码字符串 - 禁止混用字面量和
styles键：clsx('button', styles['button--primary'])❌，因为'button'没经过模块映射，构建后可能根本没被打包进去
SSR 场景下 BEM 类名为何会触发 hydration mismatch
Next.js 14 默认启用 SSR，而某些 BEM 工具依赖客户端运行时环境（比如基于 window 判断主题），会导致服务端生成的 class 名和客户端 hydration 时不一致，React 直接报 Prop className did not match。
- 必须确保所有类名在构建时静态可预测：用 CSS Modules 原生能力，而不是运行时拼接
block__element--modifier - 禁用任何在
getServerSideProps或getStaticProps中动态生成 class 名的逻辑 - 修饰符状态必须由组件 props 控制，而非服务端计算；例如
disabled来自props.disabled，而不是process.env.NODE_ENV === 'production' - 开发时建议配置
localIdentName=[name]__[local]___[hash:base64:5]，编译后类名带原始语义，一眼可查来源，避免混淆
最易被忽略的一点：BEM 的双下划线和双横线不是“为了好看”，而是 stylelint-selector-bem-pattern、postcss-bem-linter、VS Code 插件识别结构的语法边界——写成 button-icon 或 button__labelLarge，工具链就当普通类名处理，不会报错，但协作和维护成本会指数级上升。
