CSS Modules适合中大型项目基础样式隔离，Styled Components适合高频动态样式或主题切换；二者可混用，关键看样式层级、维护主体及是否需runtime控制。
CSS Modules 更适合中大型项目的基础样式隔离，Styled Components 更适合需要高频动态样式或主题切换的组件层。 两者不是非此即彼的关系，originui 和 Next.js 官方示例都同时存在两种方案——关键看你在哪一层写样式、谁来维护、是否要 runtime 控制。
CSS Modules 的引入和使用限制
CSS Modules 不是“随便 import 一个 .css 就行”，必须满足三个硬性条件：.module.css 后缀、构建工具（如 Webpack/Vite/Next.js）默认启用支持、类名必须通过 styles.xxx 对象访问。
- 错误写法：
import './Button.css'→ 全局污染，不生效作用域隔离 - 正确写法：
import styles from './Button.module.css'→ 类名自动哈希，styles.button是字符串如Button_button__abc123 - TypeScript 下推荐搭配
@types/css-modules或declare module '*.module.css'，否则styles.xxx会报类型错误 - 无法直接用
props动态插值，想实现 hover 状态切换得靠className={`${styles.base} ${isActive ? styles.active : ''}`}
Styled Components 的运行时开销在哪
每次渲染都调用 styled.xxx 创建函数，内部做模板字符串解析 + 样式注入 + className 生成。这不是“一次定义、永久复用”的静态过程。
- 组件频繁重渲染（比如受
useState影响的动画按钮），styled.button模板里的${props => props.color}会被反复执行 - 服务端渲染（SSR）需确保
ServerStyleSheet正确包裹，否则样式丢失或重复注入；Next.js 13+ App Router 中需配合use client+createGlobalStyle手动注入全局重置 - 打包体积增加：
styled-components运行时约 14KB gzip，比纯 CSS Modules 多出 ~8–10KB - 调试困难点：浏览器开发者工具里看到的是
sc-a1b2c3这类随机 class，不是语义化类名，排查依赖链需切到 React DevTools 的 component tab
什么时候该混用，而不是二选一
真实项目里，基础布局、表单控件、图标等低交互组件用 CSS Modules；高定制化、带主题/变体/状态机的组件（如 Toast、ThemeSwitcher、AnimatedCard）才上 Styled Components。
立即学习“前端免费学习笔记（深入）”；
- 例如 originui 的
CommandInput用 CSS Modules +@apply复用 Tailwind 原子类，而它的Tooltip动画逻辑用 Styled Components 控制transform和opacity过渡 - Next.js 页面级 layout 用
layout.module.css做栅格和间距，但其中嵌套的DarkModeToggle组件内部用styled.button驱动 theme 变量 - 不要在
styled.div里再写一堆padding: ${props => props.p}—— 这是在重复造 Tailwind 的轮子，反而丧失原子类的可组合性
真正容易被忽略的不是“用哪个”，而是「样式所有权」的边界：CSS Modules 的样式属于组件文件系统，Styled Components 的样式属于组件实例生命周期。前者改一个 .module.css 能批量影响所有引用处，后者改一个 styled.button 只影响当前组件树。这个差异，在团队协作和长期维护中比语法糖重要得多。
