跨越 1000 个 PR：Linear 如何把 React 样式系统迁移到 StyleX

Linear 将其 React 应用从 styled-components 迁移到了 Meta 的 CSS-in-JS 库 StyleX。值得关注的不只是技术选型，而是迁移规模：整个过程跨越了 1000 多个 Pull Request。

这次改造带来了更少的主线程工作量和更快的页面导航，同时也利用 StyleX 更严格的规则强化了组件边界。不过，这种约束并非没有代价——当团队习惯了 styled-components 的动态表达能力后，StyleX 的限制可能显得不够灵活。

为什么样式代码会影响导航速度

styled-components 的优势是开发体验直接：可以在组件文件中声明样式、读取 props，并动态生成 CSS。问题在于，这些便利可能把更多工作留到浏览器运行时。

在大型 React 应用中，一次页面切换通常不只是替换几个 DOM 节点，还可能伴随：

• 创建或更新样式规则；
• 计算基于 props 的动态样式；
• 注入样式标签；
• 重新计算样式并触发布局；
• 执行样式库自身的运行时代码。

单个组件的成本可能很小，但在复杂界面和频繁导航中会不断累积。Linear 在迁移后观察到了主线程工作量下降和导航速度提升，这说明样式系统也应被纳入前端性能预算，而不能只看组件渲染时间或接口延迟。

StyleX 倾向于使用可静态分析的样式声明，并把动态变化收敛到明确的组合与变量中。对工程团队而言，这既是性能策略，也是代码组织策略。

更严格的组件边界意味着什么

StyleX 的限制经常被批评为“管得太多”，但在大型代码库里，限制也可以形成架构护栏。

一个常见问题是父组件深入修改子组件内部结构：

// styled-components 中容易出现的紧耦合写法
const Sidebar = styled.aside`
  ${MenuItem} {
    padding-left: 12px;
  }
`;

这段代码让 Sidebar 知道 MenuItem 的内部样式实现。随着组件被复用，覆盖规则、选择器优先级和 DOM 结构便会形成隐性依赖。

更清晰的边界是让子组件公开有限的变体，而不是允许外部任意穿透：

import * as stylex from '@stylexjs/stylex';

const styles = stylex.create({
  base: {
    display: 'flex',
    alignItems: 'center',
    minHeight: 32,
    paddingInline: 8,
    borderRadius: 6,
  },
  compact: {
    minHeight: 28,
    paddingInline: 6,
  },
  active: {
    backgroundColor: '#eef2ff',
    color: '#3730a3',
  },
});

export function MenuItem({ compact = false, active = false, children }) {
  return (
    <button
      type="button"
      {...stylex.props(
        styles.base,
        compact && styles.compact,
        active && styles.active,
      )}
    >
      {children}
    </button>
  );
}

调用方只能选择组件明确支持的 compact 和 active 变体。它不能依赖内部类名，也不需要提高选择器权重。

这种模式并非 StyleX 独有，但 StyleX 的规则会推动团队更一致地执行它。代价是：临时覆盖会变麻烦，新增视觉状态通常需要先修改组件 API。

可以这样拆解迁移，而不是一次性重写

1000 多个 PR 反映出这更像持续性基础设施改造，而不是一次“大爆炸”式替换。其他团队可以按以下顺序实践。

1. 先盘点依赖面

下面的命令可以在现有代码库中找出 styled-components 的导入、模板声明和主题使用。运行前将 src 改成实际源码目录：

rg -n "from ['\"]styled-components['\"]|styled\.|createGlobalStyle|ThemeProvider" src

不要只统计文件数，还应把结果分成几类：

• 普通静态样式；
• 基于 props 的变体；
• 主题 token；
• 全局样式；
• 动画与关键帧；
• 跨组件选择器和复杂覆盖。

静态叶子组件通常适合最先迁移；全局样式和跨组件覆盖则应留到边界策略明确之后处理。

2. 用显式变体替换任意动态样式

假设原组件允许调用方传入任意颜色：

const Badge = styled.span`
  color: ${({ color }) => color};
`;

如果产品实际上只有成功、警告和错误三种状态，可以将其收敛为有限变体：

import * as stylex from '@stylexjs/stylex';

const styles = stylex.create({
  base: {
    display: 'inline-flex',
    paddingBlock: 2,
    paddingInline: 8,
    borderRadius: 999,
    fontSize: 12,
    fontWeight: 600,
  },
  success: { color: '#166534', backgroundColor: '#dcfce7' },
  warning: { color: '#92400e', backgroundColor: '#fef3c7' },
  danger: { color: '#991b1b', backgroundColor: '#fee2e2' },
});

const tones = {
  success: styles.success,
  warning: styles.warning,
  danger: styles.danger,
};

export function Badge({ tone = 'success', children }) {
  return (
    <span {...stylex.props(styles.base, tones[tone])}>
      {children}
    </span>
  );
}

在已经接入 StyleX 编译转换的 React 项目中，安装运行时包后即可改造这段组件：

npm install @stylexjs/stylex

StyleX 的构建插件配置会因 Babel、Webpack、Next.js 或其他工具链而异。生产环境应接入与当前构建器匹配的编译和 CSS 提取方案，而不是只安装运行时包。

3. 让两套系统暂时共存

千级 PR 的迁移不适合要求每个功能团队同时停工。更稳妥的办法是：

• 禁止新增 styled-components 组件；
• 允许旧组件继续运行；
• 修改旧组件时顺手迁移；
• 按页面或组件目录逐批清理；
• 每批改造都保留视觉回归和性能数据。

这会短期增加依赖和构建复杂度，但能控制回归范围，也方便在收益不符合预期时暂停。

性能验证不能只看打包体积

样式迁移的结果应在真实交互中验证。建议至少记录以下指标：

测试时应固定浏览器版本、设备模拟、测试账号和页面数据。一次手工点击不足以证明收益，最好对关键路线执行多轮自动化测试，并比较中位数和高分位值。

还要警惕把收益全部归因于库本身。迁移过程中，团队往往会顺便删除无效样式、减少动态分支、修正组件边界；这些代码治理同样可能贡献性能提升。

是否值得采用：先回答四个问题

StyleX 更适合重视运行时成本、组件边界和大规模一致性的团队，但未必适合所有项目。决定迁移前，可以检查：

• 当前样式运行时是否真的占用了可观的主线程时间？
• 团队能否接受更严格的静态规则和有限变体？
• 构建系统是否能稳定接入 StyleX 的转换与 CSS 输出？
• 是否有视觉回归测试和渐进式发布能力？

Linear 的案例说明，样式系统迁移可以产生用户可感知的导航收益，但代价是大量、持续而细碎的工程工作。真正值得借鉴的不是简单地把 styled-components 替换为 StyleX，而是将迁移拆小、明确组件所有权，并用性能数据验证每一阶段。