CSS Modules 引入后类名发生变化属于正常机制，并不是 bug：构建阶段会根据文件路径、原始类名以及内容生成唯一哈希。开发环境中由于 salt（例如时间戳）可能变化，类名出现跳变很常见；生产环境则通常依赖内容哈希来保证结果稳定。而 import styles 会始终映射到正确的哈希类名，因此样式依然可以正常生效。
类名变了，但 import styles 依然能准确映射
CSS Modules 的核心原理并不是类名“变化”后导致样式失效，而是把原始类名（例如 .button）在编译阶段转换成唯一的哈希类名（如 Button_button__abc123），同时生成一个 JS 对象，将 button 这个键映射到对应哈希值。你在 JSX 里写 className={styles.button} 时，实际插入到 DOM 中的是编译后的哈希类名。所以虽然浏览器里看到的 class 名称变了，但 CSS Modules 的映射关系并没有中断，页面样式仍然正常工作。
关键在于：styles 对象并不是写死的静态字符串，而是构建时自动生成的模块导出，它会与最终产出的 CSS 选择器保持严格一致。这也是为什么 CSS Modules 类名变化后依旧能正确应用样式的根本原因。
为什么改一个空格或注释，CSS Modules 类名又变了？
CSS Modules 的哈希计算通常会包含 CSS 内容本身，尤其是在生产环境中更常见。这意味着：
- 即使只是给
.button { }后面多加一个空格，[hash:base64:5]也可能生成新的结果 - 开发环境往往还会叠加模块路径、文件名，甚至热更新时间戳等 salt，因此类名变化会更加频繁
- 这不是程序异常，而是 CSS Modules 的设计目的：内容一致 → 哈希一致 → 更利于缓存；内容变化 → 哈希变化 → 避免旧样式被错误复用
styles.button 在 SSR 场景下为什么有时会不匹配？
如果服务端 Node 环境和浏览器客户端使用了不同的哈希 seed，或者构建配置不一致，就可能生成两个不同的 CSS Modules 类名。比如服务端渲染得到的是 button__xyz，但浏览器在 hydrate 时计算出的却是 button__abc，这时 React 往往会提示 “Hydration failed”，甚至可能放弃服务端输出的样式结果。
因此必须确保哈希逻辑完全统一：
- Webpack：可通过
css-loader的getLocalIdent自定义函数传入固定的seed - Vite：需要保证
build.rollupOptions与css.modules.generateScopedName配置一致，同时避免 dev 模式下出现 SSR 分歧（例如dev.ssr: true可能触发双路径哈希） - Next.js 用户通常更适合减少手动哈希配置，优先使用
styled-jsx或clsx+ 全局 class 命名约定
调试时 CSS Modules 类名总跳变，怎么让 DevTools 更稳定？
开发阶段频繁刷新后类名不断变化，确实会影响断点调试、手动覆盖样式以及截图标注。解决思路不是关闭哈希，而是让 CSS Modules 哈希尽量“可预测”：
- Webpack：可在
css-loader的modules.localIdentName中配合hashPrefix: 'dev'使用，例如[path][name]__[local]___[hash:base64:5]+hashPrefix: 'dev' - Vite：可配置
css.modules.generateScopedName: '[name]__[local]___[hash:base64:5]'，并确认没有启用与ssr相关的开发分支逻辑 - 注意：生产环境仍然应保留内容哈希（如
[hash:base64:8]），否则源码结构更容易被反向推断
