CSS Modules 将 .module.css 中的类名编译为哈希形式（如 _button_123abc）以实现样式局部化，避免冲突；仅对 import styles from './X.module.css' 生效，需通过 styles.button 使用，支持 localIdentName 自定义哈希格式，并可用 :global() 保留全局类名。
为什么 className 变成一串哈希？
这是 CSS Modules 的默认行为——它把你在 .module.css 里写的 .button 编译成类似 _button_123abc 这样的局部类名，确保不会和别的组件、第三方库或全局样式冲突。不是 bug，是核心机制。
关键点在于：只有 import styles from './Button.module.css' 这种方式引入的样式才走模块化流程；直接 import './Button.css' 就还是全局作用域。
- 只对
.module.css（或.module.scss等）后缀生效，普通.css文件不参与混淆 - Webpack/Vite 默认开启 CSS Modules，但需确认配置里没禁用
modules: false - React 中必须通过
styles.button动态取值，写死className="button"会失效
localIdentName 怎么自定义哈希格式？
默认哈希太长难调试，可以用 localIdentName 控制生成规则，比如加文件名前缀或缩短哈希长度。这属于构建工具配置项，不是 CSS 写法。
在 Webpack 的 css-loader 配置中设置：
立即学习“前端免费学习笔记（深入）”；
use: [{
loader: 'css-loader',
options: {
modules: {
localIdentName: '[name]_[local]_[hash:6]'
}
}
}]-
[name]是文件名（不含后缀），[local]是原始类名，[hash:6]是 6 位哈希 - Vite 用户改
vite.config.ts里的css.modules对象，语法一致 - 开发环境建议用
[path][name]__[local]___[hash:5]，方便定位来源文件
如何让某些类名不混淆（比如要暴露给 HTML 或 JS 操作）？
CSS Modules 默认全部局部化，但有时得留出口：比如需要被 document.querySelector('.highlight') 访问，或配合 Tailwind 的 utility class 混用。
- 用
:global(.highlight)包裹，该类名将跳过混淆，变成真实highlight - 多个类可一起写：
:global(.btn .btn-primary) - 注意：全局类一旦命名重复，就会污染，别滥用；优先考虑用 ref 或 data-* 属性代替 DOM 查询
- 如果只是想复用已有全局样式（如重置样式），单独建一个
reset.css并用普通import引入
服务端渲染（SSR）时类名不匹配怎么办？
React SSR 中，Node 端生成的 HTML 类名和浏览器端 hydrate 时的类名不一致，会触发 React 警告甚至样式丢失。根本原因是两端构建环境未共享 CSS Modules 的哈希生成逻辑。
- 确保服务端和客户端使用完全相同的
css-loader版本和localIdentName配置 - 禁止在服务端动态修改
process.env.NODE_ENV，否则哈希种子不同 - Next.js 用户注意：默认已处理，但自定义
next.config.js时别覆盖css-loader的 modules 配置 - 最稳妥做法：服务端渲染时统一用
getServerSideProps注入样式，避免依赖运行时哈希一致性
CSS Modules 的混淆逻辑藏在构建阶段，不是运行时魔法。最容易被忽略的是：同一项目里混用 .css 和 .module.css 时，忘记检查 import 方式是否匹配预期作用域。
