css modules类名“乱码”是设计行为而非bug，它通过哈希混淆（如button__clickable___3xq2a）实现样式局部作用域，防止同名class全局冲突；哈希含路径、类名及算法标识，确保唯一性与可复现性。
CSS Modules 的类名“乱码”不是 bug，是设计行为——它用哈希混淆实现样式隔离，防止全局污染。
为什么 import 后 class 名变成 Button__clickable___3xQ2a 这种形式
CSS Modules 默认启用局部作用域，会把每个 .clickable 自动重命名为带哈希的唯一标识。这不是编码错误或打包异常，而是核心机制：避免不同组件里同名 class（比如都叫 .container）互相覆盖。
- 哈希来源通常包含文件路径、原始类名、构建时 hash 算法（如
[name]__[local]--[hash:base64:5]） - Webpack 5+ 中
css-loader的modules: { auto: true }会自动识别.module.css文件并启用该逻辑 - 如果你看到的是纯数字或不可读字符串（如
_1a2b3c），大概率是localIdentName配置漏了或用了旧版默认值
如何让哈希类名更可读、可调试
开发阶段类名太长或难识别，会影响 DOM 检查和协作。你可以控制哈希生成逻辑，但不能完全禁用——否则就失去模块化意义。
- 在
css-loader配置中显式设置localIdentName，例如：[path][name]__[local]--[hash:base64:3] - 用
getLocalIdent函数自定义逻辑，比如开发环境返回原名：getLocalIdent: (context, _, localName, options) => { return process.env.NODE_ENV === 'development' ? localName : undefined; } - 注意：生产环境仍需哈希，否则无法保证多组件间 class 名绝对不冲突
第三方 CSS 库引入后类名也变乱码？那是你用错了方式
像 antd、normalize.css 这类库的样式本意就是全局生效。如果你直接 import 'antd/dist/reset.css' 却又开了全局 CSS Modules，它们也会被哈希化——结果是 .ant-btn 变成 _ant-btn___xyz，DOM 上根本找不到对应类，样式全失效。
- 正确做法：只对项目自有 CSS 启用 Modules；第三方 CSS 用普通
.css后缀 + 显式关闭 modules - Webpack 配置中区分处理：
rules: [ { test: /\.module\.css$/, use: [/* css-loader with modules: true */] }, { test: /\.css$/, exclude: /\.module\.css$/, use: [/* css-loader with modules: false */] } ] - 如果非要封装第三方样式（如限制 antd 只在某个区域生效），得手动拷贝进项目、重命名
antd.module.css，再用:global(.ant-btn)解除内层选择器的模块限制
乱码类名导致 React DevTools 或测试断言失败怎么办
类名哈希化后，写死的 className="button" 在测试中会匹配不到；DevTools 里也看不到直观名称。这不是样式没生效，而是查找方式需要调整。
- 测试时别依赖 class 名，改用
data-testid或 role 属性定位元素 - React 组件中若需透传 class（比如封装按钮并支持外部覆盖），用
props.className并确保它不被 Modules 处理（即不在styleName或cx()中参与哈希） - 某些 UI 库（如 Material UI）提供
classesprop 回调，可拿到实际生成的哈希类名用于定制
真正容易被忽略的是：哈希不是为了“好看”，而是为了**确定性**。只要构建环境一致，同一份 CSS 就生成相同哈希——这支撑了长期缓存、CI/CD 稳定性和团队协作基础。一旦试图绕过哈希去“还原原名”，就等于在模块边界上凿洞。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
