根本原因是构建工具对CSS模块注入时机和顺序缺乏显式控制，Webpack中MiniCssExtractPlugin按依赖图提取导致异步chunk样式错位，Vite的cssCodeSplitting使.module.css被分到不同chunk，SSR下服务端styles为空引发hydration错乱。
生产环境 CSS Modules 覆盖顺序不稳定，根本原因不是模块机制失效，而是构建产物中 .module.css 文件的注入时机和顺序在打包阶段被动态打乱——尤其是当多个组件异步加载、CSS 提取策略不一致或构建工具对 chunk 排序无显式控制时。
Webpack 中 MiniCssExtractPlugin 导致 CSS 文件顺序错位
MiniCssExtractPlugin 默认按 JS chunk 的依赖图提取 CSS，但不保证与 import 顺序严格一致。比如：
-
Button.module.css在index.tsx中import './Button.module.css' -
Modal.module.css在App.tsx中import './Modal.module.css' - 若
App.tsx被拆分为独立 chunk（如路由懒加载），其 CSS 可能晚于index.tsx的 CSS 注入<head>
结果就是 Modal 样式本该后加载以覆盖通用 Button 样式，却因 chunk 加载延迟而先插入，导致覆盖失效。解决方法是显式配置 optimization.splitChunks，把所有 module CSS 归入同一 chunk 名称，例如：
optimization: {
splitChunks: {
cacheGroups: {
styles: {
name: 'styles',
type: 'css/mini-extract',
chunks: 'all',
enforce: true,
}
}
}
}
Vite 构建时 css.codeSplitting 开启后类名注入不可控
Vite 4.3+ 默认开启 CSS 代码分割，但 composes 或跨文件引用的 .module.css 可能被分到不同 CSS chunk，且插入顺序由 Rollup 的 build.rollupOptions.output.manualChunks 决定，而非源码 import 顺序。
立即学习“前端免费学习笔记（深入）”；
- 检查最终生成的 HTML，确认
<link rel="stylesheet">是否按预期排列 - 禁用自动分割：
build: { cssCodeSplit: false }（适合中小型项目） - 或强制归一：
manualChunks: { styles: ['src/**/*module.css'] }
注意：Vite 的 css.preprocessorOptions.less.modifyVars 不影响 CSS Modules，别混淆。
服务端渲染（SSR）下 styles 对象为空引发 hydration 错乱
Next.js 或自建 SSR 应用里，import styles from './X.module.css' 在 Node 环境返回空对象 {}，客户端 hydrate 时注入的哈希类名与服务端渲染的字符串类名不一致，浏览器会重排样式流，造成短暂闪动甚至覆盖逻辑错乱。
- 不能依赖
styles.xxx在服务端生成 class 字符串 - SSR 必须配合
styled-jsx或emotion的 SSR 支持方案，或改用 CSS-in-JS +cache同步 - 若坚持用 CSS Modules，需在
getServerSideProps中提前收集所有用到的styles对象并序列化传给客户端
真正难的不是让某个组件样式生效，而是让所有 .module.css 的哈希类名在构建后仍保持可预测的层叠位置——这要求你既管住 JS 的 chunk 分割逻辑，也得盯紧最终 HTML 里 <link> 的物理顺序。任何一环交给默认行为，都可能在上线后突然翻车。
