在React项目中运用CSS Modules避免全局样式污染，核心理念很直接：每个类名在构建阶段都会自动转换为包含文件标识与哈希值的唯一名称。只要文件后缀名、导入路径和构建配置三者保持一致，样式就能实现天然隔离——并非依靠人工排查防止冲突，而是从物理层面杜绝了类名重名的可能。
很多开发者都遇到过这样的困扰：className={styles.button}，但最终渲染出的类名仍然是 button？这并非React报错，而是构建阶段根本没有生成 styles 对象。以下是几种常见原因：
- 文件后缀名错误——必须使用
.module.css，写成.css或.module.scss均无法生效，除非已配置相应的loader import styles from './Button.module.css'路径填写有误，或大小写不一致（macOS/Linux 环境下button.module.css与Button.module.css被视为不同文件）- Webpack 项目中遗漏了
css-loader的modules: true配置；Vite 项目使用了.css后缀却期望模块化功能生效 - 在
dangerouslySetInnerHTML中直接硬编码class="button"——模块化类名仅存在于 JS 对象中，不会自动注入全局作用域
如何确认CSS Modules是否正常启用？打开DevTools查看元素class属性，如果看到类似 Button_button__Kx2f1 这样带哈希值的类名，说明配置正确；如果仍然显示原始 button，则表明CSS Modules未成功运行。
动态拼接 className 时 styles[variant] 返回 undefined 该如何处理？
在进行动态className拼接时，例如写成 className={`${styles.button} ${styles[variant]}`}，很容易出现问题——因为 variant 对应的值可能并未在CSS文件中定义。
解决方案非常直接：
- 先校验存在性：
styles[variant] ?? ''或styles[variant] || '' - 更稳妥的做法是使用对象解构默认值：
const { primary = '', large = '' } = styles; - 不要依赖运行时拼接字符串——CSS Modules的类名在编译期就已确定，
styles['large']在构建时若不存在，返回值就是undefined，而非空字符串
:global() 并非万能逃生舱，滥用反而扩大样式污染范围
:global() 是唯一能够“逃逸”模块作用域的方式，但使用边界必须清晰明确：
- ✅ 正确场景：
:global(.ant-modal) { z-index: 9999; }（覆盖第三方库样式）、:global(*) { box-sizing: border-box; }（重置基础样式） - ❌ 错误场景：将整个组件样式包裹进
:global()；在子组件中使用它去“修复”父组件未导出的类名；将其作为BEM命名的替代方案 - ⚠️ 注意：通过
@import './reset.css'引入模块文件的内容，实际上仍然是全局CSS，等价于直接使用:global()，并非“安全引入”方式
哈希类名每次构建都发生变化，是系统故障吗？
这不是系统故障，而是有意设计。哈希值基于文件路径、内容甚至构建顺序生成，修改一行CSS代码或移动文件位置都会触发更新。这对缓存机制和热更新非常有利，但需要注意以下几点：
- 不要在E2E测试中硬编码
Button_button__abc123这类选择器——应使用 data-* 属性或测试专用class - 服务端渲染（SSR）时，客户端与服务端的哈希值必须保持一致，否则会引发样式闪烁；确保两端使用相同的构建配置和依赖版本
真正容易被忽视的关键点在于：CSS Modules解决的是类名冲突问题，但对于 body、html 或全局伪类（如 :focus-visible）这类规则依然无法处理——它们天生就应该全局生效，需要借助路由级样式清理或CSS-in-JS方案来兜底。
