CSS Modules 是 React 中最轻量稳定的样式私有化方案，通过构建时重命名类名实现作用域隔离；需以 .module.css 命名，导入后 styles 为哈希类名对象；:global() 仅限顶层或后代选择器中使用；HMR 失效多因导入顺序变动或混用普通 CSS；基础样式应抽离为非模块化 base.css。
CSS Modules 是 React 项目中实现样式私有化的最轻量、最稳定方案，不需要额外 runtime，也不依赖第三方库。它通过构建时重命名类名来隔离作用域，天然避免全局污染。
文件命名必须带 .module.css 后缀
在 create-react-app（CRA）中，CSS Modules 默认只识别以 .module.css 结尾的文件。命名不匹配会导致样式完全不生效，且控制台无任何报错提示。
-
Button.module.css✅ 正确，会被启用模块化 -
Button.css❌ 普通 CSS，全局注入，类名不哈希 -
Button.modules.css❌ 拼写错误，被当作普通 CSS 处理
导入方式和普通 CSS 一样：
import styles from './Button.module.css';
但此时 styles 是一个对象，键为原始类名，值为生成的唯一哈希类名（如 Button__error___2xQaF）。
:global() 的用法边界很窄
当你需要穿透模块作用域（比如复位第三方组件样式、覆盖 Ant Design 默认 margin），只能用 :global()，但它有严格限制：
立即学习“前端免费学习笔记（深入）”；
Ainative React Sdk
下载
使用 @ainative/react-sdk 为 React 应用添加 AI 聊天和积分。适用于 (1) 安装 @ainative/react-sdk，(2) 使用 useChat hook 实现聊天完成。
-
:global(.reset-button)✅ 合法：顶层直接包裹选择器 -
.container :global(.icon)✅ 合法：作为后代选择器的一部分 -
.container { :global(.icon) { ... } }❌ 不合法：不能嵌套在局部规则块内 -
:global()内部的选择器不会被哈希，会真实输出到 DOM，务必谨慎使用
热更新时 className={styles.xxx} 失效的常见原因
这不是 bug，而是 HMR（热模块替换）与哈希类名生成机制不一致导致的典型现象：
- 修改了父组件中
import样式模块的顺序（比如把A.module.css和B.module.css调换位置） - 条件性导入样式（如
process.env.NODE_ENV === 'dev' && import('./Debug.module.css')） - 在同一个文件里混用
import styles from './X.module.css'和import './Y.css'，后者可能干扰前者哈希计算
临时解决办法是手动刷新页面；长期建议保持导入顺序稳定、避免动态导入样式模块。
别把所有样式都塞进 .module.css 文件
当发现大量使用 :global() 或频繁需要 composes 继承外部类时，说明设计已偏离 CSS Modules 的初衷：
- 基础重置、字体定义、工具类（如
.sr-only）应抽离为base.css单独引入，不走模块化 - 主题变量、颜色 token 推荐用 CSS 自定义属性（
--primary-color），而非靠:global()注入 class -
composes只适合小范围复用（如.button-base+.primary），跨组件继承易形成隐式耦合
真正难处理的，不是怎么写私有样式，而是什么时候该放弃私有——比如 UI Kit 组件库的通用样式，本就不该“私有”。
