三种组件库主题方案在生产环境跑了半年，CSS 变量、CSS-in-JS 和 Tailwind 各自的坑和甜头

把组件库的主题系统拆成三种主流方案——CSS 变量、CSS-in-JS 和 Tailwind——在生产环境同时跑满半年，这个实验从第一天就不是为了找出“哪个更好”，而是要看清每种方案在真实业务压力下会暴露出什么缺陷，又在哪些场景里确实省了成本。结论很明确：没有银弹，只有用对场景。 CSS 变量最适合需要运行时动态切换主题且不依赖构建工具的场景；CSS-in-JS 在主题值需要参与复杂逻辑推导时优势最大，但性能开销需要精细控制；Tailwind 的主题方案在构建期固定主题的业务里几乎零运行时成本，可一旦要求用户实时切换主题，短板就暴露得相当彻底。

CSS 变量：运行时灵活性的代价是组织成本

CSS 变量的核心甜头在于，它能用最贴近浏览器底层机制的方式实现主题切换，无需 JavaScript 介入样式计算。我们的组件库在 :root 上挂了一套语义化变量，比如 --color-surface-primary、--color-text-on-surface，切换主题时只需要给根元素换个 data 属性，所有引用这些变量的地方自动生效，性能开销几乎可以忽略——浏览器在样式计算阶段就完成了变量替换，不会触发额外的重排重绘。

但半年下来，CSS 变量方案最大的坑不在性能，而在命名和类型约束的缺失。一个组件库动辄上百个变量，没有类型系统兜底，变量名拼写错误只有在浏览器里才能发现。我们踩过的典型事故：某个开发者在暗色主题下写成了 --color-surfce-primary（少了 a），组件在亮色主题下一切正常，暗色模式下直接塌成一片黑，而这种问题 TypeScript 完全帮不上忙。后来我们给所有变量加了 Stylelint 自定义规则做静态检查，才算勉强兜住。

另一个容易被低估的问题是变量值的语义污染。CSS 变量是纯字符串，无法约束值的含义。设计师原本定义 --spacing-md 是 8px，有人顺手写了个 --spacing-md: 1rem，这在根元素 16px 字体下看起来一样，但一旦某个容器改了 font-size，间距就全乱了。这种问题排查起来极其痛苦，因为 Chrome DevTools 里所有变量值都显示为最终计算值，你根本看不出原始定义是 px 还是 rem。

还有一点必须提：CSS 变量的继承特性在组件封装场景下是双刃剑。它方便了主题覆盖，但也意味着任何一个祖先元素修改了变量，子组件的行为就会发生变化。这在 Shadow DOM 隔离下不是问题，但我们的组件库为了兼容性没有全面启用 Shadow DOM，结果出现了主题变量被中间层无意污染的情况——一个业务方在自己的样式里写了 --color-primary: red，导致整个子树的所有组件主色全变，排查了半天才发现是继承链的问题。

CSS-in-JS：主题值的类型安全与逻辑推导，代价是运行时开销

我们用的是 Emotion，主题方案基于 React Context 传递一个 theme 对象，所有样式通过 props.theme 访问。这个方案最大的甜头是TypeScript 的类型推导可以精确到主题对象的每一个字段。开发者在写 theme.colors.primary 时有完整的自动补全，字段改名有编译期报错，不存在 CSS 变量那种拼写错误到运行时才暴露的问题。

更关键的是，CSS-in-JS 让主题值可以参与 JavaScript 逻辑推导。我们的组件库有一个场景：按钮的 hover 状态颜色需要基于主色做算法计算（HSL 模式下 lightness 降低 10%）。用 CSS 变量很难做这种计算，但用 Emotion 可以直接在样式定义里写 lighten(0.1, theme.colors.primary)，逻辑清晰且可测试。这种能力在需要基于主题值做大量衍生计算的设计系统中，是 CSS 变量很难替代的。

但运行时开销是绕不开的坑。Emotion 在每次 theme 对象变化时，会重新计算所有依赖它的样式并插入 <style> 标签。我们的组件库在页面初始化时要渲染 200+ 个组件，theme 注入触发了大量样式重计算，首屏渲染时间比 CSS 变量方案多了约 120ms（Lighthouse 性能面板实测，Chrome 118）。我们做了两个优化才把差距缩小到可接受范围：一是用 React.memo + 浅比较减少不必要的样式重计算；二是将主题对象拆分成“静态部分”和“动态部分”，只有真正需要运行时变化的值（如用户自定义的品牌色）才走 Context 传递，其他固化的设计 token 直接编译成静态 CSS。

另一个生产环境暴露的问题是 SSR 场景下的样式注入顺序。Next.js 的服务端渲染中，Emotion 的样式插入发生在组件渲染时，如果多个 chunk 的加载顺序不一致，可能导致客户端 hydrate 时样式优先级错乱。我们遇到过 dark 主题的样式被 light 主题覆盖的情况，根因是服务端和客户端的样式注入顺序不同，最后通过 @emotion/cache 显式指定插入位置并固定 key 值才解决。

Tailwind：构建期主题的极致性能，但动态切换是硬伤

Tailwind 的主题方案本质上是把设计 token 编译成原子类，运行时只是切换 class 名称。我们的组件库用 Tailwind 的主题配置定义了颜色、间距、圆角等 token，组件内部全部用语义化 class 组合。这套方案的运行时成本几乎为零——切换主题就是换一个根元素的 class（如 dark 换成 light），浏览器只需要重新匹配 CSS 规则，不涉及任何 JavaScript 计算。

这种构建期方案在生产环境的最大甜头是包体积和性能的确定性。CSS 变量的方案需要在 CSS 文件里保留所有变量定义，CSS-in-JS 需要在 JS bundle 里携带 theme 对象并在运行时注入样式，而 Tailwind 的方案最终产出的就是一份纯静态 CSS 文件。我们的组件库用 Tailwind 方案时，CSS 产物体积比 CSS 变量方案小了约 40%（PurgeCSS 去掉了未使用的原子类），首屏 CSS 解析时间快了约 15%。

但坑也非常明确：如果你需要用户在运行时实时切换主题，Tailwind 的方案就极其受限。因为它依赖构建期生成所有可能的主题变体，意味着你必须在构建时枚举所有可能的主题。我们的场景只支持亮色和暗色两种主题，Tailwind 的 darkMode: 'class' 完美覆盖。但如果业务需要支持用户自定义品牌色（比如企业客户上传自己的 logo 并生成配套的调色板），Tailwind 就完全无能为力了——你不可能在构建时预生成所有可能的颜色组合。

我们还踩了一个 Tailwind 主题配置的维护坑：设计 token 的命名与 Tailwind 的 utility class 命名之间的映射关系，全靠配置文件的手动维护。设计师改了某个色阶的名字，开发者需要在 tailwind.config.js 里同步修改，然后所有组件里引用的 class 名称也要批量替换。虽然可以用 ESLint 插件做部分检查，但相比 CSS-in-JS 那种 TypeScript 原生支持的类型安全，维护成本高了一个量级。后来我们写了一个脚本，从设计 token 的 JSON 源文件自动生成 Tailwind 配置和对应的 TypeScript 类型定义，才算把这个问题控制住。

三种方案的选择决策框架

半年下来，我们总结了一套决策逻辑，核心看两个维度：主题变化的时机和主题值的复杂度。

如果主题完全在构建时确定，运行时不需要任何变化，Tailwind 是最优解。它的零运行时开销和极小的 CSS 体积是另外两种方案无法比拟的。

如果主题需要在运行时切换，但切换的内容是有限集合（如亮/暗模式、几个预设的品牌色方案），CSS 变量是最合适的方案。它的运行时性能接近原生，且不需要 JavaScript 参与样式计算。但需要在工程层面补齐类型约束，Stylelint 自定义规则和设计 token 的 TypeScript 类型导出是必须的配套工具。

如果主题值需要参与复杂的逻辑计算（颜色推导、基于数值的间距缩放等），或者主题对象本身结构高度动态（如完全由用户自定义的调色板），CSS-in-JS 是唯一能胜任的方案。但必须投入精力做性能优化，尤其是首屏样式注入的控制和 SSR 场景的样式优先级管理。

这三种方案在我们的组件库里并不是互斥的。实际上，我们最终的设计是将主题 token 分成三层：基础 token（颜色、间距的原始值）用 CSS 变量定义，保证运行时可切换；语义 token（如“主色”“成功色”的语义映射）用 Tailwind 的原子类在构建期固化；组件级样式用 Emotion 处理需要逻辑推导的部分。三层各司其职，避免了单一方案承担所有职责带来的系统性风险。

常见问题

CSS 变量和 Tailwind 能一起用吗？会不会有冲突？

可以，而且实际项目中常常需要配合使用。Tailwind 从 v3.0 开始原生支持在配置文件中引用 CSS 变量，比如 colors: { primary: 'var(--color-primary)' }，这样 Tailwind 生成的原子类底层就依赖 CSS 变量，既能享受 Tailwind 的开发效率，又保留了 CSS 变量的运行时切换能力。需要注意的点是，PurgeCSS 在扫描时不会分析 CSS 变量的引用关系，如果你的变量名是通过字符串拼接动态生成的，需要手动配置 safelist。

CSS-in-JS 的性能开销到底有多大？什么量级的数据可以接受？

以 Emotion 11 为例，在我们的实测中（MacBook Pro M1, Chrome 118），单次 theme 对象变化触发的样式重计算耗时在 5-15ms 之间（取决于依赖该 theme 的组件数量）。如果页面有 200+ 个组件同时依赖 theme，首屏的样式注入总耗时大约 80-150ms。这个量级在大多数 B 端后台系统里是可以接受的，但在 C 端对首屏速度要求苛刻的场景（如电商首页），建议把不参与动态切换的样式提前编译成静态 CSS 文件，只保留最小化的动态样式走 CSS-in-JS 方案。

如果我用 Tailwind 但未来可能要支持用户自定义主题，迁移成本有多大？

比较大。从 Tailwind 的构建期主题方案迁移到运行时动态主题，本质上是把样式生成时机从构建期挪到运行期。这意味着你需要把 Tailwind 的配置文件映射关系反向拆解成 CSS 变量或 JavaScript theme 对象，然后逐个组件把 bg-primary-500 这类原子类替换成 CSS 变量引用或 CSS-in-JS 的 theme 访问。我们在一个 60+ 组件的项目里做过类似的迁移评估，预估工作量在 2-3 人周。建议在架构选型阶段就明确未来 12 个月内的主题需求边界，如果动态自定义主题有明确的业务规划，不要为了短期效率选 Tailwind。