CSS Modules 是中大型团队和长期项目刚需，需文件名加 .module.css、导入用 import styles、类名通过 styles.xxx 访问；全局样式用 import './base.css'，二者作用域隔离；动态类名须预定义，TypeScript 需类型声明保障编辑器提示。
没有“最佳”方案，只有适配当前项目阶段和协作习惯的方案。中大型团队、长期维护项目优先用 CSS Modules；高频动态样式或主题切换组件才考虑 styled-components；小项目或快速原型，import './App.css' 完全够用。
什么时候必须用 .module.css？
当你遇到以下任一情况时，CSS Modules 就不是“可选”，而是刚需：
- 多个开发者并行开发，已出现
.header、.btn类名被意外覆盖 - 组件库（如 Ant Design）和业务组件混用，需要防止
margin/font-size被全局重置污染 - CI/CD 中出现样式错乱但控制台无报错——大概率是普通
import './Button.css'导致的类名冲突
关键动作：文件名必须为 Button.module.css，导入必须写成 import styles from './Button.module.css'，且所有类名都通过 styles.xxx 访问。漏掉任一环节，就退化为普通 CSS。
为什么 import './base.css' 和 import styles from './Button.module.css' 能共存？
它们根本不在一个作用域层级，不是“混用”，而是分工明确：
立即学习“前端免费学习笔记（深入）”；
-
import './base.css'：用于全局重置、字体定义、CSS 变量（:root）、工具类（如.sr-only），它本就应该全局生效 -
import styles from './Button.module.css'：只负责该组件内部结构样式，类名哈希后天然隔离 - 二者同时存在时，
base.css里的.btn不会影响Button.module.css里生成的Button_button__abc123
注意：不要在 .module.css 文件里 @import './base.css'——这会破坏模块边界，构建工具通常也不支持。
动态类名拼接容易踩的坑
CSS Modules 的 styles 对象是静态编译结果，运行时不存在“按需生成类名”的能力：
-
className={styles['button-' + size]}❌ 失效：因为button-large没在原始 CSS 文件中声明，就不会出现在styles对象里 -
className={`${styles.button} ${isActive ? styles.active : ''}`}✅ 正确：所有用到的类名（button、active）都必须显式写在.module.css文件中 - 想实现状态驱动的变体？提前在 CSS 文件里定义好：
.button--primary、.button--disabled，再通过 JS 切换字符串
别试图用 JS 动态构造类名字符串去绕过编译期检查——那等于放弃 CSS Modules 的核心价值。
TypeScript 下不加类型声明会怎样？
如果不配置类型，styles.xxx 会被推导为 any，编辑器无法提示可用类名，拼错 styles.btn（实际是 styles.button）只能等到运行时才发现：
- 推荐做法：在
src/react-app-env.d.ts（CRA）或src/env.d.ts（Vite）中添加：declare module '*.module.css' { const classes: { [key: string]: string }; export default classes; } - 更严格方案：用
@types/css-modules，但需配合css-loader的modules.exportLocalsConvention配置，否则驼峰类名（如btnPrimary）访问不到
这个步骤常被跳过，但它直接决定团队成员能否在写 JSX 时获得准确的类名补全——不是锦上添花，而是基础体验门槛。
