CSS Modules 未生效导致哈希类名冲突，根本原因是配置错误或文件命名不规范；正确配置需在 vite.config.ts 中设置 css.modules.generateScopedName 包含 [path]，并确保使用小写 .module.css 后缀及正确插件支持。
哈希类名冲突说明 CSS Modules 根本没生效
看到 .button 编译成类似 Button_button__abc123 和 Header_button__xyz789 这种带路径片段的类名，说明配置已起效；但如果多个组件里都出现 button__1a2b3c 这种“缺路径、仅靠文件名+类名生成”的哈希，那不是哈希撞了，是 Vite 压根没走 CSS Modules 流程。
常见失效原因包括：
-
vite.config.ts里显式写了css: { modules: false }（哪怕只有一行） - 用了
.module.scss但没配@vitejs/plugin-sass，Vite 退化为原生 CSS 处理，跳过模块化 - 文件名写成
Button.css或button.Module.css（大小写敏感，必须小写.module.css） - 在 SSR 或服务端组件（如 Next.js Server Component）中 import，Node 端返回空对象
{}，导致客户端 hydrate 时 class 名不一致
Vite 必须显式配置 generateScopedName
Vite 默认启用 CSS Modules，但默认的哈希规则不含路径，localIdentName 这个 Webpack 概念在 Vite 里对应的是 css.modules.generateScopedName。不设它，就只能靠文件名和类名生成哈希，跨目录同名类必然冲突。
正确配置方式（vite.config.ts）：
立即学习“前端免费学习笔记（深入）”；
export default defineConfig({
css: {
modules: {
generateScopedName: '[path][name]__[local]___[hash:base64:5]'
}
}
})
关键点：
-
[path]是相对src的路径（如components/Button.module.css→components_Button__button___） - 必须用三个下划线
___分隔，避免与路径或类名中的下划线混淆 -
[hash:base64:5]足够唯一且便于调试；别用:8或:md5，构建变慢且无必要 - 该配置只对
.module.css、.module.scss等生效，普通.css文件不受影响
验证是否真正生效的唯一方式
别看配置写了没、控制台报错没，打开 DevTools，直接 inspect 元素，看 DOM 上的 class 属性值：
- ✅ 正确：
components_Button__button___aBc2d（含路径、双下划线、三段分隔、短哈希） - ❌ 失效：
button___1a2b3c（缺路径）、Button_button__xyz（旧版默认格式，不含[path]）、button（纯原始名，完全未模块化）
注意：哈希每次构建都会变——这不是 bug，是内容指纹机制；如果哈希固定不变，反而说明构建工具没接管该文件。
JS 中硬编码 className="button" 导致“样式消失”
CSS Modules 的哈希类名只存在于 JS 导入对象里，DOM 不会自动识别字符串 "button"。写死字符串等于绕过模块化机制。
错误写法：
<button className="button">Click</button>
<button className={`btn ${isPrimary ? 'primary' : ''}`}>Click</button>
正确写法：
import styles from './Button.module.css'
<button className={styles.button}>Click</button>
<button className={`${styles.btn} ${isPrimary ? styles.primary : ''}`}>Click</button>
额外注意：
-
composes: primary from './Base.module.css'要求被引入的Base.module.css也必须是.module.css后缀，否则导入的是全局 CSS，primary不会被哈希 - 动态拼接时混入非
styles字符串（如第三方类名、服务端传来的 class），会导致局部作用域被意外打破
