一个做了大半年的中台项目,全局样式文件攒到两千多行。有天产品说列表页的标题太大,开发把 .title 的字号从 20px 改成 16px,提交、发布、下班。第二天三个页面同时被反馈「标题怎么变小了」:首页的欢迎语、订单详情的主标题、设置页的区块标题,全都用了这个类。

另一个团队走了相反的路。他们把所有样式改成原子类,模板变成这样:一行里二十个 class,间距、颜色、圆角、阴影全堆在标签上。刚开始确实不再有类名冲突,但改一个间距要在十几个文件里搜索同一串类名,代码评审时没人看得清一个按钮到底长什么样,新人上手第一句话是「这个 mt-3 到底是多少像素」。

这两种痛苦不是「写法选错了」这么简单。它们分别对应样式方案要解决的两件事:一是这段样式属于谁,二是它什么时候被计算出来。这篇把 CSS Modules、原子化、运行时 CSS 三种主流做法摆在一起,讲清楚各自拿什么换什么,最后给出一条从全局 CSS 迁移到 CSS Modules 的具体路径。

改一个类,为什么能牵动三个页面

CSS 的默认作用域是全局的。只要选择器写的是 .title,页面上所有带这个类名的元素都会命中,不管它在哪个组件、哪个页面、由谁维护。浏览器不知道「这个 title 属于订单详情」,它只认类名。项目越大,同名越难避免,因为大家给标题起名的时候都会想到 title、header、content、item 这几个词。

更隐蔽的是加载顺序。全局样式最终会打进一个或几个 CSS 文件,谁后加载谁覆盖。开发环境里页面是按需加载的,你在本地看到的是「详情页的 title 生效」;线上可能因为某个页面先加载,顺序反过来,变成另一个样式赢。于是同一个类名在本地和线上表现不同,排查时很容易怀疑到框架或缓存头上。

很多团队的第一反应是加前缀,写 .order-detail-title、.setting-section-title。这能缓解,但靠人记规矩,不靠机制。三五个人的时候大家还能遵守,三十个人的时候总会有人写一个 .title,而且他本地看不出问题。命名约定是软约束,作用域才是硬约束。

原子化走的是另一条路:不解决命名冲突,而是让类名不再具有业务含义。类名只描述「一个间距」「一种颜色」,组合出来的样式属于使用它的那段模板,天然不会互相覆盖。代价是把「这段界面长什么样」从 CSS 文件搬到了模板里,可读性和修改成本换了个位置。

所以选方案不是选哪个先进,而是选把复杂度放在哪:命名约定、模板类名串,还是运行时的计算。三种都要付账,只是账单长得不一样。

拆成四个词:命名空间、作用域、复用、构建时机

讨论样式方案时,很多争论其实是四个不同的问题混在一起。把它们拆开,选择会清楚很多。

命名空间:同一个类名会不会撞车,撞了之后谁负责改
作用域:一条样式规则能影响多大范围,是全局还是一棵子树
复用:公共的间距、颜色、排版怎么被多个组件共享,又不互相绑定
构建时机:样式是打包时生成、运行时注入,还是浏览器解析时计算

命名空间解决「撞车」,作用域解决「越界」,复用解决「重复」,构建时机决定「性能账单什么时候付」。CSS Modules 主要解决前两个,原子化主要解决复用和一致性,运行时 CSS-in-JS 把构建时机推到了浏览器里。没有一个方案四项全赢,所以真实项目经常是组合使用。

先分清「隔离」和「复用」不是一回事

隔离做得好,复用往往变难。每个组件把自己的样式锁死,公共的按钮风格就要么复制多份,要么抽成一个所有人都依赖的公共模块。抽出来之后,改它又会影响所有人,回到了起点。健康的做法是分两层:一层是设计令牌(颜色、字号、间距、圆角),全局共享且稳定;一层是组件样式,局部作用域,允许各写各的。令牌少而稳,组件多而散,两层不要混在一个文件里。

这也是为什么「把所有样式都模块化」经常失败:颜色和间距这类本来就该全局统一的东西被拆进几十个文件,改一次主题要改几十处。判断标准很简单:这个值改了,应该全站一起变,还是只有这个组件变?前者放令牌,后者放组件。

CSS Modules:类名在打包时变成局部变量

CSS Modules 不是一个新的 CSS 语法,它是一层构建处理。你仍然写普通的 CSS,文件后缀改成 .module.css,构建工具会把里面每个类名替换成带哈希的唯一名字,同时导出一个对象,让你在组件里按原名引用。

/* OrderCard.module.css */
.card {
  padding: 16px;
  border-radius: 8px;
  background: #ffffff;
}

.title {
  font-size: 16px;
  font-weight: 600;
}
// OrderCard.jsx,构建环境:支持 CSS Modules 的打包器
import styles from "./OrderCard.module.css";

export default function OrderCard({ order }) {
  return (
    <div className={styles.card}>
      <h3 className={styles.title}>{order.no}</h3>
    </div>
  );
}

构建之后,styles.title 的实际值可能是 OrderCard_title__3f9a 这类名字。页面上不会再有裸的 .title,所以别的组件写 .title 也影响不到它。这就是「局部作用域」:不是浏览器支持了作用域,而是构建阶段把名字改成了不会撞的。

它解决的正是开头那个故障。改 OrderCard.module.css 里的 title,只有订单卡片变,首页和设置页不受影响。代价是每个组件多一个 CSS 文件,类名不能直接拿去给外部用;调试时看到的类名带哈希,需要在开发者工具里对照源文件。

还有一个常见误解:CSS Modules 不等于「不能用全局样式」。重置样式、字体、CSS 变量、第三方组件库的样式,仍然应该放在全局文件里。模块化的是业务组件的样式,不是所有 CSS。

composes:复用类名,但不复制声明

组件内部经常有「警示状态的标题」这种组合:字号和字重跟普通标题一样,只多一个颜色。CSS Modules 提供了 composes,让一个类组合另一个类的声明,不用在模板里拼两个类名。

/* OrderCard.module.css */
.title {
  font-size: 16px;
  font-weight: 600;
}

.warnTitle {
  composes: title;
  color: #b45309;
}

模板里只写 styles.warnTitle,最终元素上会同时带上 title 和 warnTitle 两个哈希类名。复用的是声明,不是字符串,所以不会出现「拼错一个类名,样式静默失效」的问题。

composes 也能引用另一个模块的类,比如 composes: heading from "./typography.module.css";。这很方便,但要克制:一旦组件样式依赖另一个组件的模块文件,两个组件的改动就绑在了一起。跨组件复用优先走设计令牌或公共基础样式,不要用 composes 织一张依赖网。

原子化:把样式拆成不可再分的类

原子化的思路是提供一大堆只做一件事的类:一个类管一个间距,一个类管一种颜色,一个类管一种字号。写界面时在模板里组合这些类,而不是新写一条 CSS 规则。Tailwind 是这套思路最流行的实现,但原子化本身不依赖某个库。

<div class="flex items-center gap-4 rounded-lg border border-slate-200 p-4">
  <span class="text-sm font-medium text-slate-500">下单时间</span>
  <span class="text-base text-slate-900">2026-11-06 09:12</span>
</div>

这段模板不写任何新 CSS,样式全部来自已有的原子类。好处很直接:不再需要为「订单卡片头部」这种一次性结构起名字;间距和颜色只能从一套预设里选,不会出现 13px、17px、19px 这种随手写的值;改版时调整设计尺度,改配置就能全站生效。

它真正卖的不是「少写 CSS」,而是约束。项目里最常见的样式问题是每个人凭感觉写数值,最后页面看起来差不多,但间距、字号、圆角到处不一样。原子化把这些值收进一份配置,让可选范围变窄。窄了才一致。

代价:模板变长,审查变难,规范成了硬依赖

模板一行二十个类,是原子化最直观的代价。一个复杂卡片可能要拼四十个类,读代码时先要在脑子里把类名翻译成样式。条件样式更麻烦:不同状态拼不同类,字符串拼接一多,很容易漏掉一个空格或者拼错一个修饰词。

第二个代价是审查。传统 CSS 改动可以在 diff 里看到「字号从 16 变成 14」,原子类改动看到的是「text-base 换成 text-sm」,评审的人必须记住这套映射。设计稿和实现的对应关系,从样式表转移到了类名表上。

第三个代价是硬依赖设计规范。原子化的前提是有一套说得清的颜色、间距、字号尺度。如果设计团队每次都给新数值,原子类就得不断加自定义值,最后变成「原子类 + 一堆内联样式」,约束反而没了。没有设计规范的团队上原子化,通常会在三个月后得到一坨更长的类名串。

第四个代价是构建配置。原子类由构建工具扫描模板生成,扫描范围配错、类名动态拼接、运行时才决定类名,都会导致「类写了但样式没生成」。它不报错,只是静默消失。

运行时 CSS-in-JS:动态能力的账单

styled-components、emotion 这一类方案,把样式写在 JavaScript 里,组件渲染时生成类名并插入样式表。它最强的能力是样式能直接读 props 和主题,不需要预先写一堆修饰类。

// styled-components 写法,具体版本行为待确认
const Card = styled.div`
  padding: ${(props) => (props.dense ? "8px" : "16px")};
  border-radius: 8px;
  background: ${(props) => props.theme.surface};
`;

上面的 ${(props) => ...} 是模板字符串里的插值,运行时才会算出具体值。这种动态能力在做主题、密度切换、复杂变体时很顺手:不用提前穷举所有组合,样式跟着数据走。

账单也在这里。样式要在浏览器里计算和插入,组件越多、渲染越频繁,开销越明显。服务端渲染时还要处理「样式什么时候收集、怎么塞进首屏 HTML」,否则会出现首屏无样式、 hydration 后闪一下的问题。具体到某个版本如何抽取、是否支持并发渲染,不同库和版本差异较大,这里标「待确认」,不要在项目里凭印象选型。

包体积也要算。运行时库本身要进 bundle,样式字符串也要进 bundle。一个只用了几次的卡片,可能因此多出几十 KB。对于内容型站点,这笔账通常不划算;对于交互复杂、主题多变的后台,可能值得。

编译期方案是另一条路:写法类似 CSS-in-JS,但构建时就把样式抽成静态 CSS,运行时只剩下类名。它试图同时拿到「写在组件旁边」和「零运行时开销」,代价是构建配置更复杂、动态能力受限。具体工具和版本这里不展开,选型时确认它是否支持你的构建链和 SSR 即可。

主题靠 CSS 变量,构建时机决定上限

不管选哪种方案,主题都不该硬编码在组件里。最稳的做法是 CSS 变量:组件只引用变量名,具体值由主题层决定。切主题就是换一组变量值,不需要重新生成样式,也不需要 JavaScript 参与每个组件的渲染。

:root {
  --color-bg: #ffffff;
  --color-text: #1f2937;
}

[data-theme="dark"] {
  --color-bg: #111827;
  --color-text: #e5e7eb;
}

.card {
  background: var(--color-bg);
  color: var(--color-text);
}

这段 CSS 在任何静态项目里都能直接跑:把 data-theme="dark" 加到 html 上,卡片颜色立刻切换。它和 CSS Modules 也兼容:模块文件里照常写 var(--color-bg),变量仍在全局定义。级联和变量继承的细节可以看层叠与继承,现代选择器和颜色函数的用法在现代 CSS那篇。

变量适合「值会变、结构不变」的主题;不适合「结构本身要变」的场景,比如暗色模式下列表要换一套布局。后者该由组件逻辑处理,不要硬塞进 CSS。

构建时机则决定方案的上限。打包时生成 CSS,首屏最快,但动态能力弱;运行时生成,动态强,但首屏和 SSR 要多做功课;原子化在构建时扫描生成,介于两者之间,但依赖扫描配置。选型时先问「我的样式需要多动态」,再问「我能不能接受构建配置的复杂度」,顺序反了就会为用不上的能力付账。

完整场景:两千行全局 CSS 怎么迁到 CSS Modules

需求很具体:一个运营后台,全局 app.css 两千三百行,六个页面共享。最近连续出现三次样式串页,团队决定迁到 CSS Modules,要求迁移期间不能停功能,线上不能出现大面积视觉变化。

第一版方案很激进:把所有类名加上页面前缀,再整体改成 .module.css。上线后出了两个问题:重命名靠人肉搜索,漏了动态拼接的类名,几个弹窗失去样式;原本共享的按钮、表单、表格被拆进各模块,同一个按钮在三个页面长得不一样。

正确的是「先分边界,再搬文件,最后收公共」。第一步,盘点全局选择器,标成基础、组件、页面三类:基础是重置、字体、变量;组件是按钮、输入框、表格;页面是各页布局。第二步,只把后两类搬进模块文件。第三步,类名改成 styles.xxx,构建后确认没有裸类名。第四步,把重复的按钮、表单样式抽成公共模块或令牌。

迁移顺序
盘点选择器,分成基础、组件、页面
页面样式搬进 module.css
组件改用 styles 引用
抽公共样式,删掉旧全局规则

迁移中最容易踩的是「动态类名」。原来写 className={"btn " + type},其中 type 是 primary 或 danger,这种拼出来的类名在 CSS Modules 里拿不到哈希。正确做法是用映射对象:styles[type],或者提前写两个常量。构建工具不会替你把运行时字符串也一起改掉。

第三方组件库的类名是全局的,不能塞进模块文件,也不该被模块化规则改写。业务侧覆盖时用一个单独的全局文件,把范围收在组件库的类名下面。

迁移后样式归属清楚了,但下面这些现象仍会出现。

现象真实原因第一步查什么
三个页面的标题同时变小全局 .title 被共用,改一处影响所有引用全局搜这个类名出现在哪些文件,再看加载顺序
本地样式正常,线上错乱两份同名全局样式被打进不同的 chunk,加载顺序不定看构建产物里同名选择器有几份,谁后加载
搬进 module 后某个弹窗没样式类名是运行时拼出来的,没走 styles 映射搜模板里的字符串拼接和 className 表达式
原子类写了但没有效果构建扫描没覆盖这个文件,或类名拼错看生成的 CSS 里有没有这个类,再核对模板路径
切暗色主题后部分文字不变颜色硬编码成十六进制,没走 CSS 变量搜样式里的颜色值,统计哪些没引用变量
首屏出现无样式的一闪运行时注入的样式晚于 HTML 到达看首屏 HTML 里有没有内联的关键样式

第二条特别值得说。很多「线上样式错乱」不是方案问题,而是打包拆分后同一段全局 CSS 被重复引入。在浏览器里搜最终样式表,看同一选择器出现几次;两次以上先查引入路径,不要改权重。

边界与代价:什么时候别换方案

三种方案都有明显的适用边界,超过边界继续加码,维护成本会陡增。

  • CSS Modules 在组件上百后会显得碎:每个组件一个文件,跨组件共享要么走 composes 织依赖,要么靠全局令牌和纪律。这时该补令牌和组件库,不是继续拆文件。
  • 原子化在状态多、条件类名大量出现时,模板会难以阅读。它适合结构稳定、规范明确的界面;设计天天变,原子配置追不上,最后靠内联样式兜底。
  • 运行时 CSS-in-JS 在内容型站点、SSR 首屏要求高的项目里通常不划算。它的动态能力在主题和变体多的后台更有价值,但也要接受运行时开销和调试成本。
  • 项目只有三五个页面、两三个人维护,全局 CSS 加一套命名约定就够了。上 CSS Modules 或原子化,收益抵不上构建配置和团队学习成本。
  • 样式方案不能替代设计规范。没有统一的颜色、字号、间距,换什么方案都会长出新的混乱;反过来,有规范但方案太弱,规范只能靠人记。
  • 迁移本身有风险。一次性全量替换,出问题时很难定位是哪一步造成的;分批迁移、每批跑视觉对比,代价更小。

一个实用的判断:如果团队的主要痛点是「改一个地方影响别处」,优先上作用域;如果痛点是「每个人写的间距字号都不一样」,优先上约束;如果痛点是「主题和变体太多,CSS 组合爆炸」,才考虑运行时方案。先对准痛点,再选工具。

今天就能验证的练习,和小结

  1. 在静态页面里写两个组件都叫 .title 的全局样式,确认后者覆盖前者;再把其中一个改成 .module.css,看构建后的类名。
  2. 用 CSS Modules 写一个 .warnTitle,通过 composes: title; 复用字号字重,只额外加颜色;在开发者工具里确认元素上确实有两个哈希类名。
  3. 用原子类写一张卡片,然后故意把某个类名拼错一个字母,看样式是否静默消失;再检查生成的 CSS 文件里有没有这个类。
  4. 写一组 :root 和 [data-theme="dark"] 变量,用按钮切换 html 的 data-theme,确认颜色立刻变化且不需要重新加载页面。
  5. 把一段全局样式迁进模块文件,统计迁移前后最终 CSS 总体积和同名选择器数量,确认没有重复引入。
样式冲突的根因是全局作用域加同名类,命名约定只是软约束,构建期改名才是硬隔离。
CSS Modules 解决归属,composes 解决组件内复用;跨组件复用要走令牌或公共基础样式,别织依赖网。
原子化用约束换一致,代价是模板冗长、审查困难和设计规范依赖;没有规范别硬上。
运行时 CSS-in-JS 买的是动态能力,付的是运行时开销、SSR 复杂度和包体积,版本差异要实测。
主题用 CSS 变量,构建时机决定方案上限;迁移先分边界,再搬文件,最后收公共。

样式和组件结构稳定下来之后,下一个重复劳动会浮出来:按钮、输入框、日期选择器、弹窗,这些结构在三个项目里各有一份。样式方案解决的是「每个组件怎么长得不一样」,解决不了「同一个组件为什么被复制了三遍」。下一篇组件库与可复用组件设计接着讲:什么时候该用现成库、受控和非受控怎么设计、无障碍和样式覆盖怎么留口子、版本和 breaking change 怎么管。样式是组件的皮,组件是样式的载体,先把皮的问题收住,再谈怎么把组件沉淀成资产。