CSS Modules通过构建时重命名类名（如.button→Button_button__abc123）从物理层面隔离样式，解决全局冲突；import './Button.css'因未启用modules配置，导致样式注入全局style标签，所有同名类均被匹配。
React项目里CSS选择器全局冲突不是“会不会发生”的问题，而是“什么时候爆发”的问题——只要用了 .button、.header 这类通用类名，且没做隔离，冲突就已存在。
为什么 import './Button.css' 会污染全局？
普通 CSS 导入（如 import './Button.css'）本质是把样式注入 <style> 标签，所有类名都在全局作用域生效。哪怕只在 Button 组件里用，.button 仍会匹配页面中任意 class="button" 的元素，包括第三方组件或兄弟组件里的 DOM。
- Webpack/Vite 默认对
.css文件启用css-loader，但不开启modules: true—— 这就是“全局”行为的默认配置 - 即使你只在组件内写
className="button"，浏览器照样按全局规则匹配，和 React 渲染逻辑无关 - DevTools 里看到 class 是原始名（如
button），而非Button_button__Kx2f1，说明模块化根本没启用
Button.module.css 不生效的常见硬伤
文件名后缀、导入路径、构建配置三者必须全部对齐，缺一不可。任一环节出错，styles 对象就为空或为 {}，JSX 中 className={styles.button} 渲染出来就是空字符串。
-
Button.css或Button.module.scss（但没配sass-loader+css-loader?modules）→ 构建阶段不识别为模块，返回空对象 -
import styles from './button.module.css'（路径小写）vs 实际文件是Button.module.css→ macOS/Linux 下大小写敏感，导入失败 - Vite 项目用了
.css后缀却期望模块化 → Vite 默认只对.module.css启用模块化，.css永远全局 - 在
dangerouslySetInnerHTML里写class="button"→ 模块类名只存在于 JS 对象中，不会自动注入全局样式表
动态类名写成 ${styles[variant]} 为啥是 undefined？
styles[variant] 是运行时取值，但 CSS Modules 的类名映射在构建期就固定了。如果 variant 值（比如 "large"）没在 .module.css 文件里明确定义为类名，styles.large 就是 undefined，不是空字符串。
立即学习“前端免费学习笔记（深入）”；
- 别拼字符串：
className={`${styles.button} ${styles[variant]}`→variant错误时会渲染出class="Button_button__xxx undefined" - 安全写法：用可选链或默认值，例如
className={`${styles.button} ${styles[variant] ?? ''}`，或提前校验variant是否在Object.keys(styles)中 -
:global()不是补丁工具——把它当“兜底”写在组件样式顶部，反而让整个文件失去局部性；只用于明确需要穿透的场景，如覆盖.ant-modal
@import 全局 CSS 到 .module.css 文件里等于白干
@import './reset.css' 写在 Button.module.css 里，导入的仍是全局样式。它等价于在 <style> 标签里直接写 reset.css 内容，不会被模块化处理。
- 想重置基础样式，应单独建
reset.module.css并在入口处导入，或用:global(*)显式声明 - 想复用第三方库样式（如
iconfont），必须用:global(.icon-home)包裹，否则类名会被哈希化，图标无法显示 - 哈希值每次构建都变是正常行为——它依赖文件路径、内容、甚至 webpack 模块 ID 顺序，改一行 CSS 或移动文件位置都会触发变更
真正卡住人的从来不是“怎么开开关”，而是“哪一环悄悄失效了”。DevTools 里看 class 名是不是带双下划线哈希，是唯一可信的验证方式；其他任何“看起来能跑”，都不代表 CSS Modules 在工作。
