CSS Modules通过文件后缀（如.module.css）和构建配置（如Webpack的modules:true、Vite默认识别）实现样式局部作用域，避免全局污染；普通.css文件仍为全局样式，需严格匹配配置与命名规则。
CSS Modules 本身不解决跨浏览器问题，它解决的是作用域污染——而作用域污染在所有浏览器里都存在，只是表现一致。真正需要关注的，是构建配置是否生效、类名是否被正确哈希、以及动态类名拼接时是否漏掉边界检查。
为什么 import './Button.css' 还是全局污染？
因为 .css 后缀默认不启用模块化。Webpack 和 Vite 都只对 .module.css（或显式配置了 modules: true 的规则）做局部作用域处理。普通 .css 文件会被当作全局样式注入 <style> 标签，浏览器照常按全局 CSS 规则匹配——不管你是 Chrome 还是 Safari。
- Webpack 项目必须确认
css-loader配置含modules: true，且localIdentName有定义（如[name]_[local]_[hash:base64:5]） - Vite 默认仅识别
.module.css；.css永远全局，改后缀是最简单可靠的方案 - Umi 用户可配
cssModulesWithAffix: true让.css也走模块化，但需手动开启，非默认行为
styles.button 渲染为空字符串？三个硬性条件没满足
不是 React 报错，而是构建阶段压根没生成 styles 对象。常见原因只有三个：
- 文件后缀不对：必须是
Button.module.css（或.module.scss，且已配好sass-loader+css-loader?modules） - 导入路径或大小写错误：
import styles from './button.module.css'在 macOS/Linux 下找不到Button.module.css（大小写敏感） - 在
dangerouslySetInnerHTML里硬写class="button"——模块类名只存在于 JS 对象中，不会注入全局样式表，浏览器根本看不到这个类
className={`${styles.button} ${styles[variant]}`) 导致 undefined？
CSS Modules 的类名映射是编译期静态确定的。styles[variant] 如果 variant 值未在 .module.css 中明确定义为类名（比如文件里只有 .small 和 .large，但传入 "xlarge"），结果就是 undefined，不是空字符串。
立即学习“前端免费学习笔记（深入）”；
- 错误写法：
className={`${styles.button} ${styles[variant]}`→ 可能输出class="Button_button__xxx undefined" - 安全写法：
className={`${styles.button} ${styles[variant] ?? ''}` - 更稳妥：提前校验
Object.keys(styles).includes(variant)，避免运行时拼字符串
:global() 不是万能补丁，乱用反而扩大污染面
:global() 是唯一能“逃逸”模块作用域的方式，但它的使用边界必须清晰：
- ✅ 正确场景：
:global(.ant-modal) { z-index: 9999; }（覆盖第三方库）、:global(*) { box-sizing: border-box; }（重置基础样式） - ❌ 错误场景：把整个组件样式包进
:global()；在子组件里用它去“修复”父组件样式——这等于主动放弃模块隔离，回到全局污染原点
真正容易被忽略的是：CSS Modules 的哈希类名在构建时就固定了，调试时看到原始类名（如 button）基本说明模块化根本没走通，别急着调样式，先查构建配置和文件后缀。
