CSS Modules专为大型组件化项目设计，解决类名冲突与作用域污染，而非单文件过大问题；必须按组件拆分（如UserCard.module.css），禁用composes，用clsx组合复用样式，并通过:global()显式暴露全局规则。
CSS Modules 本身不是为“大型 CSS 项目”设计的，而是为“大型组件化项目”服务的——它不解决单个 CSS 文件过大问题，而是解决类名冲突、作用域污染和协作耦合问题。
为什么不能把整个项目塞进一个 .module.css 里？
CSS Modules 的核心机制是「每个 .module.css 文件对应一个 JS 模块作用域」。这意味着：
- 类名哈希只在当前文件内唯一，跨文件同名类（如
.title）会被编译成不同哈希，互不影响 - 但如果你把所有样式写在一个
App.module.css里，就等于放弃了模块边界——styles.header和styles.cardTitle全挤在一起，编辑器无法跳转、重构无提示、复用成本高 - 构建时仍会生成一个大 CSS 文件，但失去了按组件拆分、按需加载、独立测试的能力
组件级拆分：一个组件 = 一个 .module.css + 一个 React 组件
这是最稳定、最易落地的结构。比如一个用户卡片：
- 路径：
src/components/UserCard/UserCard.tsx+src/components/UserCard/UserCard.module.css - 导入方式必须是：
import styles from './UserCard.module.css'，不是import './UserCard.module.css' - 类名必须通过
styles.root、styles.avatar访问，禁止硬编码className="avatar" - TypeScript 项目中，建议配
declare module '*.module.css'类型声明，否则styles.xxx会报错
复用逻辑怎么抽？别用 composes，改用 clsx + JS 组合
composes 是 CSS Modules 的遗留语法，实际项目中容易踩坑：
立即学习“前端免费学习笔记（深入）”；
- Vite 默认不支持
composes，Webpack 需要css-loader≥ v6 且显式开启modules.compose - 路径解析不走 Webpack alias，
composes: title from '@styles/typography.module.css'会静默失败 - 无法动态组合，比如根据 props 切换变体
更可靠的做法是：把基础样式写进独立模块（如 shared/Typography.module.css），然后在组件里用 clsx 组合：
import typography from '../shared/Typography.module.css';
import styles from './Button.module.css';
<button className={clsx(typography.body, styles.root, props.primary && styles.primary)} />
全局样式和重置怎么留口？用 :global() 显式透出
CSS Modules 不是全封闭沙盒。需要全局生效的部分（如 CSS Reset、字体定义、工具类）必须显式声明：
- 写法：
:global(.reset) { margin: 0; padding: 0; }或:global(body) { font-family: sans-serif; } - 不能放在
.module.css里靠运气生效——只有加了:global()才真正脱离模块作用域 - 建议单独建
src/styles/reset.module.css和src/styles/utils.module.css，并在入口main.tsx中import './styles/reset.module.css'
真正的难点不在怎么拆，而在于团队是否接受「每个视觉单元都必须有明确归属」——按钮样式归 Button.module.css，哪怕只有一行 padding；页脚背景色归 Footer.module.css，哪怕只是 background: #333。一旦松动，模块化就退化成命名约定。
