css modules 通过构建时重命名类名为哈希值（如button_button__kx2f1）从根源避免样式冲突；失效主因是文件后缀非.module.css、路径错误、构建配置缺失或硬写class；验证看浏览器中类名是否含文件名与哈希。
CSS Modules 不是靠“约定”或“自觉”避免冲突，它直接在构建时把 .button 这种类名重写成带哈希的唯一标识，比如 Button_button__Kx2f1。只要文件后缀是 .module.css、导入方式正确、构建工具配置到位，冲突就从根源上消失。
为什么 className={styles.button} 会失效或变成 undefined
这不是 React 写法错，而是构建阶段根本没生成样式映射对象。常见原因有：
- 文件名不是
.module.css（比如写成Button.css或Button.module.scss却没配好 Sass loader） -
import styles from './Button.module.css'的路径错误，大小写不一致（尤其在 macOS/Linux 上） - Webpack 项目里漏了
css-loader的modules: true配置；Vite 项目里用了.css后缀却期望模块化生效 - 在 HTML 字符串模板或
dangerouslySetInnerHTML里硬写了class="button"—— 模块类名只存在于 JS 对象中，不会自动注入全局
如何验证 CSS Modules 是否真正启用
打开浏览器开发者工具，检查目标元素的 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.button} ${styles[variant]}` 看似合理，但风险很高：
- 如果
variant是'large'，但Button.module.css里没定义.large→styles.large是undefined，最终 class 变成"Button_button__xxx undefined" - 更安全的写法是用数组过滤：
className={[styles.button, styles[variant]].filter(Boolean).join(' ')} - 或者提前校验：
const variantClass = styles[variant] ?? '' - 别用字符串拼接去构造
styles['btn-' + type]，除非你 100% 控制type的取值范围且每个 key 都在 CSS 文件中显式声明
哈希类名的生成逻辑依赖文件路径 + 原始类名 + 当前作用域内容，这意味着哪怕两个组件都叫 .icon，只要不在同一个文件里，就不会冲突——这个机制不靠人盯，靠构建工具硬保证。最容易被忽略的，其实是文件命名和 import 路径这两个看似最基础的环节。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
