BEM命名在SSR中易出错，因服务端与客户端class名生成不一致会触发hydration mismatch；必须确保class名静态可预测、样式构建时提取，禁用运行时拼接。
不能直接用传统 BEM 工具链（如或）在 Gatsby/Next.js的 SSR 场景下安全工作，除非你显式处理服务端与客户端的 class 名生成一致性。
为什么 BEM 命名在 SSR 中容易出错
服务端渲染时，CSS-in-JS 库（如
、
）或 CSS Modules 会为组件生成唯一 class 名。但纯字符串拼接的 BEM 写法（如
）在服务端和客户端可能因执行顺序、环境差异导致 class 名不一致，触发 React hydration mismatch 错误：
——看起来一样，实则因 JS 执行时机或哈希逻辑不同，服务端输出的 class 名与客户端 hydration 时生成的不一致。
服务端没有
、
，部分 BEM 工具依赖运行时环境
未启用 SSR 支持的 CSS-in-JS 插件（如
）会导致样式丢失或错位
手动拼接 BEM 字符串无法参与构建时 CSS 提取（如 Gatsby 的
），失去 scope 隔离优势
Next.js 中安全使用 BEM 的两种可行方式
核心原则：class 名必须在服务端和客户端完全相同，且样式能被正确提取到 HTML 中。
php版微信js-sdk支付接口类
php版微信js-sdk支付接口类
下载
立即学习
“
前端免费学习笔记（深入）
”；
用 CSS Modules + 手动 BEM 命名：文件名保持
，在 CSS 文件中写
、
，JS 中通过
引用 —— 构建时由 Webpack 确保 class 名稳定，SSR 安全
用
+ CSS Modules 组合修饰符：
，然后
—— 避免字符串模板，所有 class 名都来自模块对象
禁用
或
中的动态 class 生成逻辑；BEM 修饰符状态应由组件 props 控制，而非服务端计算
Gatsby 中 BEM 的推荐落地路径
Gatsby 默认是 SSG（静态生成），比 Next.js 的 SSR 更“确定性”，但依然要求 class 名跨构建与运行时一致。
优先使用
+
插件：它在构建时将
规则编译为真实 class 名，不依赖运行时，天然 SSR 安全
避免在
中引入任何会改变 class 生成逻辑的 BEM 工具（如基于
的 BEM provider）
若用 Tailwind，可借助
插件生成
类，配合
和
配置确保命名可控，且完全静态
最容易被忽略的细节：CSS 提取时机与 hydration 顺序
即使 class 名一致，如果样式没随 HTML 一起下发，客户端 hydration 后会出现“闪动”或布局偏移。Gatsby 和 Next.js 都要求：
Next.js：在
中正确注入
或
的 SSR 样式；用
+
确保服务端样式内联
Gatsby：必须启用
或
，并确保其配置在
中排在靠前位置，否则 BEM class 可能未被识别为局部作用域
所有 BEM 相关的
、
、
规则，必须在构建阶段完成解析 —— 运行时动态
CSS 文件会破坏 SSG/SSR 流程
bem-css-modulesbem-cnstyled-componentsemotion`block__element--modifier`Warning: Prop `className` did not match. Server: "header__title--large" Client: "header__title--large"windowdocument@emotion/servergatsby-plugin-postcssComponent.module.css.header__title.header__title--largestyles.header__titleclsximport styles from './Button.module.css';className={clsx(styles.button, modifier && styles['button--primary'])}getServerSidePropsgetStaticPropsgatsby-plugin-postcsspostcss-bem@bemgatsby-ssr.jsReact.createContext@tailwindcss/bem.block__elementprefixseparator_document.tsxemotionstyled-componentsCacheProviderextractCriticalgatsby-plugin-sassgatsby-plugin-postcssgatsby-config.js@import@layer:where()import()