在React项目中引入SCSS模块化，初衷是为了实现样式隔离、避免类名冲突，并借助自动哈希提升代码可维护性。然而，许多开发者在实际配置过程中，常会遇到一系列典型问题：文件后缀已改为.module.scss，但类名仍未哈希化；TypeScript编译时报“找不到模块”错误；或样式看似生效，类名组合却出现异常。这些现象看似孤立，实则共同指向一个核心：CSS Modules的完整启用与运行，并非仅靠修改文件后缀即可实现，它依赖于构建工具、类型系统与CSS解析逻辑三者的协同配置。
SCSS文件已添加.module.scss后缀，但className未哈希化
当你发现className={styles.button}最终渲染为class="button"，而非预期的class="Button_button__abc123"这类哈希字符串时，基本可判定CSS Modules并未被真正激活。这通常并非文件命名错误，而是构建工具未能将其识别为模块化CSS进行处理。
具体原因因构建工具而异：
- Create React App (CRA)：对文件后缀有严格约定，必须使用
.module.scss（注意module为必需字段）。只要后缀正确，CRA会自动启用CSS Modules，无需额外配置。若项目已执行eject，则需检查webpack.config.js中cssRegex与getStyleLoaders相关规则，确保modules选项已应用于匹配.module.scss文件的规则。 - Vite：默认支持
.module.scss，但需留意vite.config.ts中的css.modules.generateScopedName配置。若该配置被覆盖或设置不当，可能影响局部类名的生成。此外，若在全局配置中启用了css.modules，又在单个SCSS文件中混用:global规则，也可能导致作用域行为异常。 - Webpack 5+：存在版本配置差异。在新版
css-loader中，仅设置modules: true可能已无法生效，建议采用更明确的写法：modules: { mode: 'local' }，以确保模块化模式被正确激活。
遇到此类问题，首先应检查导入语句：正确写法应为import styles from './Button.module.scss'，而非具名导入（如import { button } from './Button.module.scss'，后者会导致styles为undefined）。若styles为空对象或undefined，类名哈希化自然无法实现。
TypeScript报错“找不到模块‘./X.module.scss’”
此错误表明TypeScript编译器在编译阶段即受阻，无法识别*.module.scss文件类型，因此阻止导入。这并非样式失效，而是类型系统缺失对应声明。
解决方案是为SCSS模块文件添加类型声明。推荐在项目根目录或src目录下创建声明文件（如src/react-app-env.d.ts或globals.d.ts），并加入以下内容：
declare module '*.module.scss' {
const content: Record;
export default content;
} 需注意：声明应精确匹配*.module.scss，而非泛泛的*.scss。后者虽能消除报错，但会使普通.scss文件也通过类型检查，丧失模块化CSS提供的类型安全优势。
若希望获得更佳的开发体验（如编辑器自动提示类名），可考虑使用typings-for-css-modules-plugin等工具，或在构建时自动生成.d.ts文件。但对多数项目而言，上述声明已足够。完成后，请确认tsconfig.json的include字段已包含声明文件路径，并在VS Code中通过“Ctrl+Shift+P”执行“Restart TypeScript Server”以使新声明立即生效。
样式生效但类名组合异常
有时样式看似正常，但当尝试组合多个类名（如className={`${styles.button} ${styles.disabled}`}）时，仅第一个类名被正确应用。这通常与SCSS的书写方式及CSS Modules的哈希规则有关。
关键在于理解：CSS Modules通常仅对顶层选择器进行哈希映射。对于SCSS中的嵌套规则（如.button:hover）或后代选择器（如.button .icon），它们不会生成独立的、可映射的类名，而是作为哈希化后父类名的一部分存在。
例如，若SCSS代码如下：
.button {
color: red;
&:hover {
color: blue;
}
}在JS中仅需引用styles.button，编译后生成的:hover规则会自动关联至哈希化的.button类，悬停效果依然有效。但若尝试手动拼接类似styles.button + '__hover'的类名，则必然无效，因为映射关系中不存在此键名。
为避免此类问题，可遵循以下原则：
- 谨慎使用
@extend：该指令在模块化环境中可能破坏样式隔离，且生成的选择器难以预测。 - 采用BEM等显式命名：若需状态类，可直接在SCSS中定义如
.button--disabled的顶层类，并在JS中通过styles['button--disabled']引用。 - 避免
:global混用：在模块化文件中使用:global(.some-class)会引入全局样式，易与局部类名冲突，尤其在引入第三方库时问题更为隐蔽。
全局样式被CSS Modules意外哈希化
另一常见问题是，如normalize.css等全局重置样式被意外添加哈希，导致body标签出现class="body__xyz789"等异常类名，致使全局样式失效。
这本质是构建配置的“误伤”：处理CSS的规则未能正确区分模块化文件与全局文件，将本应全局引入的CSS也纳入了CSS Modules流程。
解决方案在于精确配置exclude或include规则：
- Webpack：检查处理CSS的规则（通常为
test: cssRegex）。需确保该规则通过exclude排除模块化文件（通常由cssModuleRegex正则定义，如/\.module\.(css|sass|scss|less)$/）。如此，.module.scss文件会走启用modules选项的规则，而普通.scss及normalize.css则按全局样式处理。 - Vite：可在
vite.config.ts中通过css.modules.exclude选项排除特定文件，例如：css: { modules: { scopeBehaviour: 'local', exclude: ['normalize.css'] } }。 - 注意导入方式：避免在
.module.scss文件中使用@import 'normalize.css';，这会导致全局样式被卷入模块化处理。正确做法是在项目入口JS/TS文件中直接import 'normalize.css';。
综上所述，CSS Modules失效的核心症结，往往不在于“如何开启”，而在于“开启后整个工具链的协同运作”。一个简单的.module.scss文件，其背后涉及构建工具配置、TypeScript类型声明与CSS预处理器解析逻辑的精密配合。任何一环配置疏漏，都可能导致模块化静默失败。理清这条协作链，问题便能迎刃而解。
