css modules未启用导致类名未哈希化，根本原因是构建工具未处理.module.scss文件：create react app需严格使用.module.scss后缀；vite需检查generatescopedname配置；webpack 5+须设modules: { mode: 'local' }，而非modules: true。
SCSS文件加了.module.scss后缀，但className还是原样没哈希化
说明CSS Modules根本没启用，不是文件写错了，而是构建工具压根没处理它。Create React App要求必须用.module.scss后缀，且不能漏掉module这四个字母；Vite默认支持，但得确认没被css.modules.generateScopedName配置意外覆盖；Webpack 5+则必须在css-loader里显式写modules: { mode: 'local' }，光写modules: true在新版里已不生效。
常见错误现象：className={styles.button}渲染出来是class="button"而不是类似class="Button_button__abc123"的哈希名——这表示样式对象里的button字段压根不存在，styles可能是空对象或undefined。
- 检查导入语句是否为
import styles from './Button.module.scss'，不是import { button } from './Button.module.scss'（后者会报undefined） - Create React App下改后缀是唯一硬性条件，无需动配置；ejected项目则要搜
cssRegex和getStyleLoaders，确保modules选项落在正确rule里 - Vite用户注意：若用了
css.modules全局配置，又在单个文件里写了:global，可能导致局部类名生成逻辑被干扰
TypeScript报错“找不到模块‘./X.module.scss’”
这是TypeScript在喊“我没见过这种文件”，不是样式不生效，而是编辑器/编译器直接拦下了导入语句。本质是缺少类型声明，让TS知道.module.scss导入后是个对象，且对象里有你写的类名。
最简方案是在项目根目录建src/react-app-env.d.ts或globals.d.ts，写一行：declare module '*.module.scss' { const content: Record<string string>; export default content; }</string>。别只写declare module '*.scss'，那会把普通.scss也放行，失去模块化校验意义。
- 如果想进一步支持智能提示类名，得用
typings-for-css-modules-plugin或自动生成.d.ts文件，但日常开发中上面那行声明已足够 - 注意
tsconfig.json里include要覆盖到这个.d.ts文件，否则声明不生效 - VS Code可能需要重启TS服务（Ctrl+Shift+P → “Restart TS server”）才能立刻识别新声明
样式生效了，但类名组合出错，比如className={`${styles.button} ${styles.disabled}`结果只有第一个生效
大概率是SCSS里用了嵌套或&语法，导致实际生成的类名和你写的不一致。CSS Modules只对顶层选择器做哈希，.button:hover、.button .icon这类后代/伪类不会单独映射，它们依赖父类名存在才能起作用。
例如SCSS里写：.button { color: red; &:hover { color: blue; } }，JS里只引用styles.button，那:hover规则仍会生效；但如果你手动拼接styles.button + '__hover'，就完全错了。
- 避免在SCSS中用
@extend，它会破坏模块化隔离，且生成的类名不可预测 - 要用BEM风格命名，如
.button--disabled，然后在JS里明确写styles['button--disabled'] - 慎用
:global(.some-class)混入全局类，容易和局部类名冲突，尤其当第三方库也用了CSS Modules时
全局样式（如normalize.css）被CSS Modules污染，变成带哈希的类名
这是配置范围误伤：Webpack或Vite的css-loader或css插件规则把本该全局引入的CSS文件也塞进了Modules流程。典型表现是body上出现class="body__xyz789"这种不该存在的哈希名，或者重置样式失效。
根本原因是exclude规则没写对。Create React App里靠cssModuleRegex自动排除.module.css等，但如果你手动配了规则，就得自己控制exclude: /node_modules/或exclude: /normalize\.css$/。
- Webpack中检查
test: cssRegex这条rule的exclude是否包含cssModuleRegex——它通常定义为/\.module\.(css|sass|scss|less)$/，目的就是让.module.css走Modules，其余走普通流程 - Vite中可在
vite.config.ts里对特定文件禁用模块化：css: { modules: { scopeBehaviour: 'local', exclude: ['normalize.css'] } } - 别在
.module.scss里用@import 'normalize.css'，这会让normalize也被局部化；应单独import 'normalize.css'在入口JS里
.module.scss文件，背后连着构建配置、类型系统、CSS解析逻辑三套规则，漏掉任意一环都会静默失败。前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
