GitHub SSR 性能优化:从 CSS-in-JS 迁移到 CSS Modules 的实践
1. 一次构建耗时砍半的改造,到底改了什么
GitHub 前端团队把服务端渲染(SSR)的耗时压低了 55%,靠的不是换框架、不是加机器,而是把样式方案从一类运行时注入的 CSS-in-JS 迁移到了 CSS Modules。这个数字放在任何一家有规模的 Web 产品上都算得上夸张,因为 SSR 的耗时大头通常被归因到数据请求、组件树深度、序列化开销上,很少有人第一反应会去动样式层。但恰恰是样式层,在 SSR 场景里藏着一笔长期被忽视的账。
先把结论摆出来:这次迁移的核心收益来自三个地方——服务端不再需要为每个请求执行样式序列化和哈希计算、客户端不再需要在 hydration 阶段重新生成样式、组件渲染路径上的 JavaScript 执行量显著下降。三者叠加,才凑出了 55% 这个量级。如果你的项目也在用 SSR 或 SSG,并且样式方案是运行时 CSS-in-JS,那这篇内容基本可以当成一份迁移参考手册来读。适合的读者包括:正在做首屏性能优化的前端工程师、维护中大型 React 应用的架构同学、以及任何对 SSR 渲染链路感兴趣的人。哪怕你暂时不打算迁移,理解这笔账是怎么算出来的,也能帮你在下一次性能评审时找到真正的大头。
需要先说明一点:GitHub 的具体实现细节官方并没有全部公开,下面涉及的操作步骤、参数取舍、排查方法,一部分来自公开的技术分享,一部分是我基于同类项目迁移经验做的合理补全。我会明确标注哪些是通用实践、哪些是推断,避免你把推测当成事实照搬。
2. 为什么运行时 CSS-in-JS 在 SSR 里这么贵
2.1 服务端渲染的样式注入到底发生了什么
要理解这次迁移的价值,得先搞清楚运行时 CSS-in-JS 在 SSR 链路里干了什么。以常见的 styled-components、Emotion 这类方案为例,当服务端渲染一个页面时,流程大致是这样的:React 开始遍历组件树,每遇到一个带样式的组件,样式库就要把这段样式定义解析出来,生成一个唯一的类名(通常基于内容哈希),把样式规则塞进一个全局的样式表收集器,然后把类名返回给组件。整棵树渲染完之后,再把收集到的所有样式规则序列化成一段 CSS 字符串,插入到返回给浏览器的 HTML 里。
这个过程听起来不复杂,但问题在于它是逐组件、逐请求执行的。一个中等规模的页面可能有几百个带样式的组件,每个组件都要走一遍「解析样式对象 → 计算哈希 → 查重 → 写入收集器」的流程。哈希计算本身是 CPU 密集操作,样式对象越复杂、嵌套越深,开销越大。而且这些工作对每个用户请求都要重来一遍,因为服务端是无状态的,没法跨请求复用样式表。
更麻烦的是序列化阶段。收集器里可能积累了几千条样式规则,要把它们拼成合法的 CSS 文本、去重、排序、处理媒体查询和伪类的嵌套,这一步在样式量大的页面上能占到 SSR 总耗时的相当比例。GitHub 这种体量的产品,页面组件数量以千计,这笔开销被放大得非常明显。
2.2 客户端 hydration 阶段的二次开销
服务端渲染完只是上半场,下半场在浏览器里。当 HTML 到达浏览器、React 开始 hydration 时,运行时 CSS-in-JS 库需要重新执行一遍样式生成逻辑,目的是让客户端的样式状态和服务端保持一致。也就是说,服务端算过的哈希、生成过的类名,客户端要再算一遍。如果两边结果不一致,就会出现样式闪烁或者 hydration mismatch 警告。
这一步的代价经常被低估。它不只是多跑一遍计算,还意味着样式库的代码必须被打进客户端 bundle,而且要在 hydration 的关键路径上同步执行。样式库本身的体积加上运行时的解析逻辑,会直接拖慢首次可交互时间(TTI)。对于追求极致首屏的产品来说,这是一笔双重负担:服务端多花时间,客户端也多花时间。
2.3 CSS Modules 为什么能绕开这些开销
CSS Modules 的思路完全不同。它在构建时就把样式处理完了:.module.css 文件经过构建工具(webpack、Vite、Rspack 等)处理,类名被确定性地哈希成唯一标识,样式被抽取成独立的静态 CSS 文件。运行时组件拿到的只是一个字符串类名,没有任何样式解析、哈希计算、收集器写入的动作。
这个差异在 SSR 场景下是决定性的。服务端渲染组件时,样式相关的开销几乎归零——组件只是引用了一个已经算好的类名,不需要执行任何样式逻辑。样式文件在构建阶段就已经生成好,服务端只需要在 HTML 里引用对应的 CSS 链接即可。客户端 hydration 时同样轻松,因为类名是静态的,不存在「重新计算再比对」的环节,样式库的运行时也基本不需要打进 bundle。
用一个类比:运行时 CSS-in-JS 像是每次做菜都现切现配,CSS Modules 像是提前把配菜切好装盒,开火时直接下锅。前者灵活,能根据运行时状态动态生成样式;后者死板一些,但快得多。GitHub 的选择本质上是承认:对于绝大多数样式需求,构建时确定就够了,没必要为少数动态场景让所有页面买单。
3. 迁移前的评估:哪些样式能迁,哪些不能
3.1 先摸清样式资产的分布
动手之前最重要的一步是盘点。一个成熟项目里的样式来源往往很杂:有纯静态的布局样式、有依赖 props 动态计算的样式、有基于主题变量切换的样式、还有依赖运行时状态(比如滚动位置、鼠标悬停坐标)的样式。这四类里,前两类和第三类的大部分都能迁到 CSS Modules,第四类通常需要保留运行时方案或者改用 CSS 变量配合少量 JS。
我的建议是先做一次全量扫描,把每个样式定义按「是否依赖运行时 JS 值」分类。依赖 props 的样式要特别小心,因为 CSS Modules 没法直接读 props,需要用类名组合或者 CSS 变量来传递。比如原来写 color: ${props => props.active ? 'red' : 'blue'},迁移后要么用两个类名切换,要么把颜色通过 style={{ '--active-color': ... }} 这种 CSS 变量注入。后者更灵活,但要注意 CSS 变量的作用域和继承规则。
GitHub 的迁移规模很大,据公开信息他们处理了海量的样式定义,其中相当一部分是可以通过构建时方案解决的。这个比例因项目而异,但经验上,一个正常迭代多年的项目,70% 到 85% 的样式是可以静态化的,剩下的才是真正需要运行时能力的部分。
3.2 主题切换是最大的拦路虎
主题(深色/浅色模式)是迁移中最容易翻车的地方。运行时 CSS-in-JS 处理主题很优雅,主题对象通过 Context 下发,样式函数直接读主题值。CSS Modules 没有这个能力,必须换一种思路。
主流做法有两种。第一种是用 CSS 变量承载主题值:在根元素上根据当前主题设置一组 CSS 变量,CSS Modules 里引用这些变量。切换主题时只改变量值,样式自动更新。这种方案的好处是切换零成本、不触发重渲染,缺点是所有主题相关的值都要预先定义成变量,动态性受限。
第二种是生成多套 CSS 文件,按主题加载不同的文件。这种做法适合主题数量固定且差异大的场景,但会增加构建产物体积和加载复杂度,一般不推荐。
GitHub 采用的是 CSS 变量为主的方案,这也是目前社区的主流选择。需要提醒的是,CSS 变量的命名规范要提前定好,否则迁移到一半发现命名冲突或者语义混乱,返工成本很高。我一般建议用「组件名-属性名-变体」的结构,比如 --button-bg-primary、--button-bg-hover,可读性和可维护性都比较好。
3.3 动态样式的兜底策略
总有一些样式是真的没法静态化的,比如拖拽时的实时位置、根据内容长度计算的宽度、canvas 相关的样式。这部分不要硬迁,保留运行时处理即可。关键是控制比例,让运行时样式的数量降到最低,同时确保它们不会污染静态样式的渲染路径。
一个实用的做法是把动态样式隔离到独立的组件里,用内联 style 或者小范围的运行时方案处理,避免整个页面因为少数动态样式而退回运行时模式。GitHub 的做法据推测也是类似的隔离思路——大部分静态化,少数动态的单独处理。
4. 迁移实操:从构建配置到组件改造
4.1 构建工具侧的配置要点
CSS Modules 的构建配置本身不复杂,但有几个细节决定了迁移的顺利程度。以 webpack 为例,核心配置是给 .module.css 文件启用 css-loader 的 modules 选项:
这里有几个参数值得展开说。localIdentName 决定了生成的类名格式,开发环境建议带上文件名和局部名方便调试,生产环境可以只用哈希来压缩体积。exportLocalsConvention 设成 camelCaseOnly 是为了让 my-class 这种带连字符的类名在 JS 里能用 styles.myClass 访问,避免写 styles['my-class'] 这种别扭的写法。
生产环境还要考虑 CSS 的抽取和压缩。用 mini-css-extract-plugin 把 CSS 抽成独立文件,配合 css-minimizer-webpack-plugin 压缩。SSR 场景下,服务端需要知道当前页面用到了哪些 CSS 文件,这通常通过构建时生成的 manifest 来实现——构建产物里记录每个入口对应的 CSS 文件列表,服务端渲染时读取 manifest 并注入对应的 <link> 标签。
注意:SSR 下千万不要用
style-loader,它会把样式通过 JS 注入 DOM,服务端没有 DOM,会直接报错。服务端必须用抽取出来的静态 CSS 文件。
4.2 组件改造的渐进式路径
一次性迁移所有组件风险太大,渐进式才是正解。我的建议是按「叶子组件 → 容器组件 → 页面级组件」的顺序推进。叶子组件样式简单、依赖少,先迁它们能快速验证方案可行性,积累经验。容器组件往往涉及主题和布局,复杂度高一些。页面级组件最后处理,因为它们通常是样式组合的汇聚点。
改造单个组件的流程大致是:把样式定义从 JS 对象或模板字符串里抽出来,写成 .module.css 文件;把原来通过 props 传的动态值改成 CSS 变量或者类名组合;在组件里 import 样式对象,用 styles.xxx 替换原来的样式引用。举个具体的例子,原来可能是这样:
迁移后变成:
这个改写模式几乎适用于所有「根据 props 切换样式」的场景。用 CSS 变量而不是直接写两套类名,好处是样式值可以在运行时被覆盖,保留了部分动态能力。
4.3 服务端渲染链路的对接
迁移到 CSS Modules 后,SSR 的样式处理逻辑要跟着改。原来服务端需要调用样式库的 ServerStyleSheet 或者 extractCritical 来收集样式,现在这些都不需要了。取而代之的是:服务端渲染组件树,得到 HTML 字符串;同时根据当前路由从构建 manifest 里查出需要的 CSS 文件;把 CSS 链接注入到 HTML 的 <head> 里。
这里有个容易踩的坑:如果用了代码分割(code splitting),每个异步加载的 chunk 可能对应独立的 CSS 文件。服务端渲染时如果只注入了主 chunk 的 CSS,异步组件首次渲染会出现无样式闪烁(FOUC)。解决办法是在 manifest 里记录完整的 chunk 依赖关系,服务端渲染时把当前路由涉及的所有 chunk 的 CSS 都注入进去。GitHub 这种规模的站点肯定做了细粒度的 CSS 拆分和注入,这也是他们能进一步压缩首屏时间的原因之一。
5. 55% 这个数字是怎么来的:收益拆解
5.1 服务端耗时的构成变化
把 55% 拆开看会更有参考价值。迁移前,SSR 耗时大致由这几块构成:数据获取、组件渲染、样式序列化、HTML 序列化。样式序列化在样式量大的页面上能占到 20% 到 35%,这是迁移后直接消失的部分。组件渲染本身也会变快,因为每个组件不再需要执行样式生成逻辑,渲染路径上的 JS 执行量下降,这部分收益大概在 10% 到 20%。
两块加起来,服务端耗时的下降幅度落在 30% 到 50% 区间是合理的。GitHub 报出的 55% 可能还包含了其他优化(比如数据获取的并行化、组件树的精简),但样式迁移无疑是主要贡献者。这个数字给我们的启示是:在 SSR 性能优化里,样式层的开销值得单独拿出来审视,它经常被数据层和组件层的优化掩盖了。
5.2 客户端指标的连带改善
服务端快了,客户端也跟着受益。最直接的是 HTML 体积变小——运行时 CSS-in-JS 会把样式序列化进 HTML,样式多的时候这段内联 CSS 能占几十甚至上百 KB。改成外链 CSS 文件后,HTML 体积下降,首字节时间(TTFB)和下载时间都改善。外链 CSS 还能被浏览器缓存,用户访问第二个页面时直接命中缓存,不用重新下载样式。
另一个改善是 JavaScript bundle 变小。样式库的运行时(styled-components 压缩后大概 12KB 到 15KB,Emotion 类似)从 bundle 里移除了,hydration 阶段也少了一大块同步执行逻辑。对于移动端用户和低端设备,这部分收益体感很明显。
5.3 缓存友好度的提升
还有一个容易被忽略的收益:CSS 文件的缓存效率远高于内联样式。运行时 CSS-in-JS 生成的样式是跟着 HTML 走的,每次请求都可能不同(因为哈希可能变化),没法被 CDN 长期缓存。静态 CSS 文件有稳定的文件名(带内容哈希),可以设置很长的缓存时间,CDN 命中率高,回源压力小。对于 GitHub 这种全球流量的站点,缓存效率的提升对整体性能的贡献不可小觑。
6. 迁移过程中最容易踩的坑
6.1 类名冲突与作用域问题
CSS Modules 默认是局部作用域的,这本来是优点,但迁移时容易出问题。如果项目里原来有全局样式(比如 reset、工具类),迁移后这些全局样式和 CSS Modules 的局部样式可能产生优先级冲突。CSS Modules 生成的类名是单个类选择器,优先级很低,很容易被全局样式覆盖。
解决办法是控制全局样式的范围,尽量用 CSS 变量和设计令牌(design tokens)来共享值,而不是靠全局类。如果确实需要全局样式,用 :global 显式声明,并且放在独立的文件里管理,避免和模块样式混在一起。
6.2 组合样式的写法差异
运行时 CSS-in-JS 支持样式继承和组合,比如 styled(Button) 可以基于已有组件扩展样式。CSS Modules 用 composes 来实现类似效果:
composes 只能组合类选择器,不能组合带伪类或媒体查询的规则,这是它的限制。迁移时遇到复杂的样式继承,可能需要拆成多个类名在 JS 里组合,或者用 CSS 变量传递共享值。
6.3 构建产物的 CSS 顺序问题
CSS 的层叠依赖顺序,而构建工具打包 CSS 时的顺序不一定和组件引用顺序一致。迁移后如果发现某些样式被意外覆盖,多半是 CSS 文件顺序变了。解决办法是显式控制 CSS 的引入顺序,或者在关键样式上加足够的特异性。这个问题在大型项目里尤其常见,建议迁移后做一次全量的视觉回归测试。
6.4 常见问题速查表
| 问题现象 | 可能原因 | 排查方向 |
|---|---|---|
| 服务端渲染报错找不到 document | 用了 style-loader | 服务端改用静态 CSS 抽取 |
| 首屏样式闪烁(FOUC) | 异步 chunk 的 CSS 未注入 | 检查 manifest 的 chunk 依赖 |
| 样式被全局样式覆盖 | 类名优先级过低 | 收敛全局样式,用 :global 隔离 |
| 主题切换不生效 | CSS 变量未更新 | 检查根元素变量设置时机 |
| 类名在 JS 里访问不到 | 命名转换配置不对 | 检查 exportLocalsConvention |
| 构建后 CSS 体积暴涨 | 未做压缩和去重 | 启用 css-minimizer 和 purge |
7. 什么情况下值得做这次迁移
不是所有项目都该跟风迁。判断标准其实很清晰:如果你的项目用了 SSR 或 SSG,并且样式方案是运行时 CSS-in-JS,同时页面组件数量多、样式复杂,那迁移的收益会很明显。反过来,如果项目是纯客户端渲染(CSR),运行时 CSS-in-JS 的开销主要在客户端,迁移收益会小一些,但 bundle 体积和 hydration 性能仍有改善。
另一个判断维度是团队对构建工具的掌控程度。CSS Modules 依赖构建配置,如果团队对 webpack 或 Vite 的配置不熟,迁移过程中遇到问题会比较被动。建议先在一个小模块上试点,跑通完整链路(构建、SSR、缓存、主题)再全面铺开。
我个人在类似迁移中的体会是:最难的不是技术,而是决心。样式层的东西牵一发动全身,视觉回归测试的成本很高,很多团队宁愿忍受性能问题也不愿冒视觉出错的风险。但如果你的 SSR 耗时确实被样式拖累,这笔账迟早要算。GitHub 用 55% 这个数字证明了,这笔投资是值得的。
最后分享一个实操小技巧:迁移期间可以保留两套方案并行,用特性开关(feature flag)控制哪些页面走新方案。这样既能灰度验证,又能在出问题时快速回滚。等所有页面都验证通过,再移除旧方案的依赖。这个过渡期可能持续几周甚至几个月,但比起一次性切换的风险,这点时间成本完全值得。