CSS Modules 通过构建时重命名类名实现样式隔离，需确保文件后缀为 .module.css、路径正确、构建工具配置启用 modules；:global() 仅限必要场景，动态拼接 className 要校验存在性，@keyframes 等仍需手动处理。
React 项目推荐用 CSS Modules，不是因为它“更现代”，而是它在构建时就把 .button 这种类名重写成 Button_button__Kx2f1 这种带文件标识和哈希的唯一值，从源头掐断样式污染——只要配置对、写法对，冲突就物理上不存在。
className={styles.button} 是空或 undefined 怎么办
这不是 React 报错，是构建阶段压根没生成 styles 对象。常见原因：
- 文件后缀不是
.module.css（比如写了Button.css或Button.module.scss却没配 Sass loader） -
import styles from './Button.module.css'路径错，大小写不一致（尤其 macOS/Linux 区分大小写） - Webpack 项目漏了
css-loader的modules: true配置；Vite 项目用了.css后缀却指望模块化生效 - 在
dangerouslySetInnerHTML或 HTML 字符串模板里硬写了class="button"—— 模块类名只存在于 JS 对象中，不会自动注入全局
浏览器里看到的 class 还是 button，不是哈希名
说明 CSS Modules 根本没启用。验证方式很简单：打开 DevTools，检查元素的 class 属性值：
- 如果看到类似
Button_button__abc123或header_Index__title___1aB2c→ 已启用 - 如果还是原始的
button、modal→ 没走模块化流程，回退检查文件后缀和构建配置
注意：哈希值每次构建可能变化，改一行 CSS 或挪动文件位置都会触发更新，这是正常行为，不是 bug。
立即学习“前端免费学习笔记（深入）”；
:global() 不是万能出口，乱用反而破防
:global() 是唯一能“逃逸”模块作用域的方式，但必须明确边界：
- ✅ 正确场景：覆盖第三方库样式（如
:global(.ant-modal) { z-index: 9999; }）、重置基础样式（:global(*) { box-sizing: border-box; }）、对接遗留 HTML 片段 - ❌ 错误场景：把整个组件样式包进
:global()；在子组件里用它去“修复”父组件没导出的类名；当成 BEM 命名的替代方案 - ⚠️ 注意：
@import './reset.css'进模块文件，导入的仍是全局 CSS，等价于直接写:global()，不是“安全引入”
动态拼接 className 时 styles[variant] 是 undefined
写 className={`${styles.button} ${styles[variant]}` 看似灵活，但极易翻车：
- 如果
variant是'large'，但Button.module.css里没定义.large→styles.large是undefined，最终 class 变成"Button_button__xxx undefined" - Vite 用户若启用了
css.modules.localsConvention: 'camelCaseOnly'，但写了class-name这种横线命名，会导致styles.class-name访问不到（应写成styles.className） - 热更新时
className={styles.xxx}偶尔失效？本质是哈希名在 HMR 过程中没同步更新，尤其修改了父组件的样式导入顺序或条件导入逻辑时容易触发
真正容易被忽略的是：CSS Modules 只处理 class 和 id 选择器，@keyframes、@font-face 仍为全局，得手动加前缀或用 :global() 隔离。
