CSS Modules 配合 ESM 实现组件样式私有化与异步水合，关键在于构建时自动局部化类名并确保动态导入的组件与样式原子性加载，服务端与客户端哈希一致以保障水合无错位。
用 CSS Modules 配合 ESM 实现组件级样式私有化与异步水合，核心在于两件事：一是让每个组件的样式在构建时自动局部化、不泄漏；二是确保动态导入的组件及其样式能与服务端渲染（SSR）或静态生成（SSG）输出正确匹配，避免水合时样式错位或闪动。
CSS Modules 的本地化机制必须启用
CSS Modules 不是语法标准，而是构建时能力。需确认构建工具已开启模块化支持：
- Vite 默认识别
.module.css文件，无需额外配置；若用其他后缀（如.module.scss），需确保对应预处理器插件已安装并启用 - Webpack 需在
css-loader中显式设置modules: true或使用modules: { auto: true }自动识别文件名含module的 CSS - 类名混淆由构建器完成，导出对象（如
styles.button）指向编译后唯一哈希类名（如Button_button__Kx9f2），天然隔离
ESM 动态导入需同步加载样式资源
React 中用 import() 异步加载组件时，其关联的 .module.css 必须一同加载，否则水合前 DOM 无样式，水合后才注入，造成 FOUC 或布局跳变：
- 推荐写法：将样式与组件共置，统一导出
.root { padding: 8px 16px; background: #007bff; color: white; }// Button.jsx
import styles from './Button.module.css';<br>export default function Button({ children }) {<br> return <button className={styles.root}>{children}</button>;<br>}// LazyButton.jsx（异步入口）
const LazyButton = React.lazy(() => import('./Button.jsx'));此时 Webpack/Vite 会自动把 Button.module.css 打包进同一 chunk，保证 JS 和 CSS 原子性加载。
立即学习“前端免费学习笔记（深入）”；
服务端渲染场景下的水合一致性保障
若项目启用 SSR（如 Next.js App Router、Remix 或自建 Express + ReactDOMServer），需注意：
- 服务端渲染时，CSS Modules 类名必须与客户端完全一致——这依赖构建时哈希算法稳定（Vite/Webpack 默认启用 contenthash，安全）
- 服务端不能执行
import styles from './X.module.css'并插入 style 标签，而应通过构建产物收集所有用到的 CSS 模块，生成<style></style>片段注入 HTML - 客户端水合时，React 对比的是 DOM 结构和 class 属性值；只要服务端与客户端使用相同构建产物、相同哈希逻辑，
styles.xxx就能精准映射，水合无 mismatch
避免常见陷阱
- 不要在动态导入的模块中再做二级
import('./xxx.module.css')，易导致样式加载时机不可控 - 禁用 CSS 提取插件（如 MiniCssExtractPlugin）对 module 文件的单独提取，否则可能破坏 chunk 关联
- 若用 CSS 预处理器（Sass/Less），确保其 loader 配置与 css-loader 的 modules 模式兼容；例如 Vite 中
.module.scss可直接用，但 Webpack 需为 sass-loader 显式传入additionalData或启用modules: { auto: true }
