前几天把一个维护了大半年的 React 18 后台项目接上 React Compiler删掉最后一批useCallback、useMemo和React.memo之后构建产物居然还变小了 3%。Table 页滚到第一千行时不再掉帧点击筛选按钮后整棵组件树的白屏闪烁也基本消失。如果你现在还在 React 18 项目里手写一堆缓存 API又担心升级成本下面这份折腾记录应该能给你一条明确的接入路线。这次折腾的目标很具体在不动业务代码、不升级 React 大版本的前提下让编译优化替我做掉大部分记忆化工作。文章里的每一步都是在 Vite React 18 项目里实际跑过的包括依赖安装、Babel 配置、ESLint 体检以及接入后踩到的几个隐蔽的坑。适合正在用 React 18、又想尽快吃上 React Compiler 红利的前端团队参考。1. 手动 memo 的尽头为什么 React 18 项目需要编译期优化1.1 手动缓存的问题不是记不住而是管不住React 18 的渲染模型大家都知道只要某个组件setState默认情况下从它开始往下的整棵子树都会重新执行函数组件。性能优化的关键就是判断这次重新执行到底有没有意义。于是社区沉淀出了一套组合拳React.memo挡住父组件重渲染引起的子组件无意义重渲染useMemo缓存昂贵计算结果useCallback给子组件传稳定的函数引用。这套方案确实有效但维护成本极高。先说依赖数组。useMemo和useCallback的依赖数组完全靠人肉维护数组里漏掉一个变量缓存就会在某个隐藏场景里悄悄失效代码不会报错只会慢慢变卡。反过来多写一个依赖缓存就会频繁失效优化形同虚设。更头疼的是这类问题极难定位你不可能在每个性能问题出现时都把依赖数组逐个核对一遍。再说包裹边界。手写缓存时人天然会以整个组件和整个对象为粒度于是经常出现两种极端要么包裹范围太粗导致一堆本不该重渲染的子树跟着重渲染要么范围太细缓存了大量其实不需要缓存的计算。团队协作就更不用提了不是每个人都愿意在写完一段逻辑后停下来想这个函数要不要包useCallback、那个对象要不要包useMemo代码 review 时也常常为了缓存边界吵来吵去。1.2 React Compiler 解决的是整个开发流程的效率问题React Compiler 的思路是把记忆化这件事从人肉操作变成编译期自动分析。它是一个 Babel 插件对组件函数做静态数据流分析自动识别出哪些值在两次渲染之间没有变化可以安全缓存然后替你把缓存代码生成出来。组件代码里不再塞满缓存 API写起来清爽正确性也由编译器来兜底。官方对它的定义是编译期自动记忆化工具并不是简单地把useMemo自动补上而是重新理解组件的数据流。对存量 React 18 项目来说这意味着不需要推倒重写、不需要升级 React 19也能让渲染优化水平上一个台阶。虽然 React 19 对编译器的运行时集成更深但 React 18 完全能承载这套优化链路。另一个容易被忽略的价值是React Compiler 是规则驱动的。它要求代码严格遵守 React 的编程模型配套的 ESLint 插件会把所有违反规则的地方暴露出来。接入后的第一轮报错某种程度上就像一次免费的全项目代码体检帮你把渲染函数里的副作用、状态可变修改这些潜在问题全部翻出来。2. React Compiler 到底改了什么从编译产物看缓存逻辑2.1 编译产物的第一印象跳进代码里的$()接入后我做的第一件事是打开构建产物看编译完的组件长什么样。原来的组件代码里JSX 还是那个 JSX但中间多了不少$调用。这是react-compiler-runtime提供的缓存函数编译器的核心逻辑就藏在这里。用一个简单的例子说明。编译前function ProductCard({ product, onAdd }) { const priceText formatPrice(product.price); return ( div span{priceText}/span button onClick{onAdd}加入购物车/button /div ); }编译后的产物大致会长成这样示意代码不是精确输出import { $ as _c } from react-compiler-runtime; function ProductCard(props) { const $ _c(); let t0; if ($[0] ! props.product.price) { t0 formatPrice(props.product.price); $[0] props.product.price; $[1] t0; } else { t0 $[1]; } // JSX 结构同样会被缓存这里省略 return div{t0}/div; }真实的编译产物比这个复杂JSX 结构也做了细粒度缓存但核心逻辑就是这一套把上一次执行的依赖输入和计算结果存进缓存下次渲染先比较输入没变化就直接复用。这里特别要提醒一句$缓存是按组件调用顺序分配存储槽位的所以组件必须严格按固定顺序调用不能条件触发。这也是为什么编译器强制要求代码遵守 Rules of React。2.2 细粒度缓存和 React.memo、useMemo 的思维方式差异React.memo是组件级缓存父组件重渲染时如果子组件的 props 引用没变整个子组件函数就不执行。useMemo是表达式级缓存只针对单个计算结果。它们本质上都是人肉标记哪些地方不该重复跑。React Compiler 的粒度比这两者都细。它可以做到只缓存一段 JSX 子树或者只缓存某个内联函数引用。举个例子一个组件内部有十行 JSX其中只有一行依赖某个 state编译器可以只让那一行对应的缓存失效其余九行直接复用上一次的 JSX 结构。手写React.memo做不到这个精度因为组件要么整体重跑要么整体不跑。这也是为什么编译器能处理那些每次写都会产生新引用的代码。像onClick{() { ... }}这种内联箭头函数只要闭包内依赖的变量没变编译器就会把函数引用缓存住子组件拿到的始终是同一个函数。从实际效果看这相当于把手写useCallback这件事彻底自动化了。还有个值得注意的点编译器不会移除你已经写好的React.memo和useMemo它会尊重这些手动缓存。但这不代表完全没有副作用后面第 4 节会专门讲和手写缓存叠加时踩到的坑。2.3 前提条件代码必须符合 Rules of React编译器能精准分析的前提是代码遵守 React 的核心规则。具体来说有四条组件和 hooks 里的 hooks 必须在顶层调用不能写在循环、条件分支里渲染期间不得直接修改 props、state 或 ref副作用必须放到 effect 或事件处理中不能在渲染函数里直接写组件必须是大写字母开头hooks 必须是use开头。只要违反任何一条编译器的数据流分析就会失真。轻则优化失效重则运行时出现诡异表现。我在接入初期就遇到过几次为什么这个组件缓存后不更新了的现场追根溯源全是代码里藏着渲染期副作用。所以官方配套的 ESLint 插件不是摆设而是整个接入方案的安全带。开发阶段它就把规则违反点暴露出来避免你把问题代码带到线上。3. 在 React 18 Vite 项目里接入 React Compiler 的完整步骤3.1 依赖安装与版本选择先把依赖装上。这里要特别注意安装环境不同包放的依赖类型不一样npm i -D babel-plugin-react-compilerbeta eslint-plugin-react-compilerbeta npm i react-compiler-runtimebetababel-plugin-react-compiler和eslint-plugin-react-compiler是编译期工具放devDependencies没问题。但react-compiler-runtime必须放进生产依赖dependencies因为构建产物在浏览器运行时会直接 import 它。如果误放成开发依赖线上部署时安装生产依赖就会少包页面直接报错这是最容易踩的第一个坑。版本选择上我的建议是直接装beta标签不要碰太旧的0.0.0-experimental版本。实验版阶段功能迭代极快旧版本的编译产物和最新的 runtime 经常不兼容。装完后把package-lock.json提交到仓库确保团队所有成员的版本完全一致。3.2 Vite 项目里打开 Babel 插件我在这个项目里用的是 Vitevitejs/plugin-react内部自带 Babel 管线不需要单独建babel.config.js。在vite.config.ts里直接追加插件就行import react from vitejs/plugin-react; import { defineConfig } from vite; export default defineConfig({ plugins: [ react({ babel: { plugins: [ [babel-plugin-react-compiler, { target: 18 }], ], }, }), ], });target: 18是告诉编译器当前运行在 React 18它的产物会走兼容 React 18 的运行时路径。如果后续升到 React 19把这里改成19即可。少数插件版本可能还不接受这个参数去掉也不影响基本使用但保留会让产物更贴合当前 React 版本。如果你的项目用的是 Webpack babel-loader配置逻辑一样把插件加进 babel-loader 的plugins数组即可。Next.js 用户更简单直接在next.config.js里开experimental.reactCompiler。至于还在 CRA 的项目需要借助craco或react-app-rewired覆盖 babel 配置相对麻烦一些我的建议是这种情况先别急着接等迁移到 Vite 或者 Webpack 直接管理再说。3.3 ESLint 规则接入与第一轮存量代码体检Babel 插件只负责生成缓存代码它不会告诉你代码哪里违反了编译规则。ESLint 插件才是前置检查员在开发阶段就抓出编译器无法正确处理的代码。配置如下export default { plugins: [react-compiler], rules: { react-compiler/react-compiler: error, }, };配完跑一遍全量检查你会看到满屏报错。这里先给个心理预期不用慌绝大多数报错就三类。第一类是渲染期间读取或修改ref.current。很多老代码喜欢在渲染函数里读ref.current判断是否有历史值这在手动缓存时代还能勉强跑编译器眼里就是高危行为。第二类是直接修改 props 或 state比如props.list.push(item)之后再setState这种可变更新会让编译器完全无法判断状态变更路径。第三类是 hooks 被写进了条件分支比如if (visible) { useFetch(...) }直接把编译器干懵。处理原则很简单能改代码就尽量改不要第一反应去关规则。存量项目如果实在不敢大动可以把规则先设为warn或者按目录忽略分模块逐步消化。我在下面第 4 节会详细讲处理思路。3.4 怎么确认编译真的在跑配置完成并不代表万事大吉一定要确认编译器真的在产出缓存代码。最直接的办法是看源码面板。打开浏览器开发者工具的 Sources 面板找到页面对应的编译后模块搜索react-compiler-runtime能看到$调用就说明插件生效了。构建产物也可以直接验证grep -rl react-compiler-runtime dist/assets/如果产物里搜不到这个字符串大概率是 Babel 配置没生效或者构建缓存还停留在旧状态。清掉node_modules/.vite和dist重新构建再试。更直观的验证方式是看 React DevTools Profiler。接入前点击一个修改父组件 state 但不涉及子组件 props的按钮整棵子树通常全部高亮重渲染接入后高亮范围会明显缩小。注意 React 18 的 StrictMode 在开发模式会双调用组件DevTools 里的高亮次数可能翻倍判断时重点看是否有不必要的兄弟节点重渲染而不是纠结绝对次数。4. 接入后我踩过的坑编译报错、运行时异常与缓存失效排查4.1 运行时提示 react-compiler-runtime 无法找到接入当天本地开发一切正常构建产物部署到测试环境后控制台直接报错Uncaught TypeError: (0 , _reactCompilerRuntime.$) is not a function。第一反应是react-compiler-runtime没装。但本地明明能跑检查 package.json 才发现npm 自动把它装到了devDependencies里。我再强调一次这个包必须手动挪到dependencies因为它是浏览器端运行时依赖不是构建期工具。排查链路是这样的先确认node_modules里有没有对应版本再看它被放进了哪个 dependencies最后检查构建工具的打包配置确认产物里是否真的引用了react-compiler-runtime。当时我们项目的manualChunks做过自定义分包第一次构建时这个包被拆进了独立的异步 chunk导致部分页面在 chunk 加载完成前就执行了组件代码。解决办法是把它跟react、react-dom放进同一个 chunk保证主包加载时就绪。清掉node_modules/.vite和dist重新构建之后问题消失。这类问题最坑的地方在于本地环境几乎复现不了必须盯着产物和线上报错信息一起排查。4.2 最扎心的一批报错ESLint 把我写得很爽的代码全标红了接入后最磨人的不是配置而是第一轮 ESLint 体检。项目里有段图表组件在渲染函数里读ref.current判断上一次的数值做动画差值计算。这在手动缓存时代是常规操作ESLint 插件直接报Ref values may not be accessed during render。一开始我想屏蔽这条规则觉得我一直这么写也没出事。但冷静下来看这段代码确实依赖渲染期的可变状态编译器无法判断它会不会影响缓存正确性。就算这次侥幸能用哪天 React 并发渲染一介入这种代码就是定时炸弹。正确的改法是把上一次的数值用useState单独存一份通过 effect 在值变化时更新或者干脆把差值计算从渲染期挪走。类似的还有先 push 数组再 setState的写法改成setState(prev [...prev, item])的不可变更新方式。我现在的态度是ESLint 报错不是来添乱的是来指路的。改完这些代码之后项目里渲染函数里除了 return 什么都不干这条纪律变得更加严格可维护性反而提升了。4.3 StrictMode 双重渲染下的缓存问题另一个让我排查了很久的问题是开启 React 18 StrictMode 后某个折线图组件在页面加载时出现闪烁一下的现象数据像是被初始化了两次。第一反应是编译器缓存和 StrictMode 冲突。于是我做了对照实验关闭 Babel 插件只在 StrictMode 下运行同一个页面闪烁依旧出现。这说明缓存逻辑本身没问题问题出在业务代码里。继续定位发现这个组件在渲染期间直接往一个模块级变量里写了数据用于图表的最近一次渲染数据快照。StrictMode 双调用让这个模块级变量被写了两遍第二次写入覆盖了第一次导致图表在挂载瞬间重新初始化。这类问题在接入编译器的过程中会被放大因为编译器生成的缓存要求组件是纯粹的函数渲染阶段不能有任何外部副作用。处理办法是把模块级变量的写入挪到 effect 里或者直接用useRef在事件处理函数中维护。踩完这个坑我对渲染纯函数这条原则有了更深的敬畏。4.4 和手写 memo 叠加后的双重缓存困惑接入后还遇到过一个最反直觉的现象某些组件在接入编译器之后反而出现该更新的没更新。比如一个列表项组件明明 props 里的数据变了页面却纹丝不动。排查过程很有意思。我先禁用编译器问题消失说明和它有关。再把组件里手写的React.memo和useMemo全部删掉问题也消失。两边一对比原因很清楚编译器生成的细粒度缓存和手写缓存形成了双重缓存。编译器会尊重你手写的缓存并不会把它们移除。但手写useMemo的依赖数组写得太宽依赖了某个每帧都在变的对象引用而编译器内部的细粒度缓存已经把 JSX 段缓存住了。两层缓存叠加后手动缓存错误地判断props 没变直接把整个子树短路了编译器完全无法感知。这个问题的解法不是去改编译器配置而是渐进式清理手写缓存。我先挑了几个页面做灰度对比重渲染行为变化再分模块把手写缓存删掉。全部删除后发现编译器生成的缓存正确接管了所有记忆化工作之前担心的删掉 memo 后性能下降并没有出现。手写缓存在这套体系下确实是冗余的而且是有风险的冗余。5. 收益放在显微镜下哪些场景提升明显哪些场景不用指望5.1 我们的项目实测数据先交代项目背景React 18.3.1 Vite 5 Ant Design 5约 8 万行代码的中后台系统。首批接入 6 个页面跑了两个星期的灰度。对比方式是同一份代码分别以开启/关闭 Babel 插件构建用 React DevTools Profiler 和浏览器 Performance 面板记录典型交互数据。指标接入前接入后说明长表格滚动时重渲染次数每秒约 30~40 次约 8~10 次编译器对列表项做了细粒度缓存滚动时只有可见行重渲染点击筛选后 Table 子树重渲染范围整棵子树全部触发明显缩小未改变 props 的表头、工具栏组件不再重渲染首次加载包体积基准2% 左右多出编译器运行时和缓存标记代码量级很小构建耗时基准5% 左右Babel 阶段多了一层数据流分析这是单个项目里的典型值不保证所有团队都能复现但趋势是一致的运行时收益远大于构建时间成本。5.2 哪些场景收益明显最明显的是高频更新 大子树的页面。我们项目里的长表格、复杂筛选表单、实时刷新的大屏看板接入后都能感受到交互变顺滑了。第二类收益明显的是大量内联对象和箭头函数传 props 的代码。这类代码原来是useCallback的重灾区现在交给编译器自动缓存闭包依赖函数引用稳定了子组件重渲染次数直线下降。还有一个容易忽略的收益面代码规范混乱的存量项目。ESLint 插件让渲染期副作用无处遁形改完一批代码后整个模块的渲染路径变得干净可控。这种长期维护价值的收益甚至比性能提升更值钱。5.3 哪些场景别指望编译优化必须泼一盆冷水React Compiler 不是万能的下面几类场景几乎没什么收益。首次加载和纯初次渲染。编译器缓存的是第二次及以后的重复计算首屏该执行的计算一样都省不掉。如果首屏性能差先查资源加载和同步计算别指望编译器兜底。每次结果都不同的场景。依赖当前时间戳、随机数、外部实时数据的渲染逻辑结果本身每次都在变缓存无从谈起。编译器再聪明也不能把一个永远变化的计算变成不变的值。渲染路径上的一次性大计算。如果一个复杂格式化函数单次执行就要几百毫秒编译器顶多让它不重复执行第一次的几百毫秒照样卡。如果你遇到的是这种问题该做的是优化算法本身不是上记忆化工具。最后说一点个人体会。接入 React Compiler 之后我现在的建议是别犹豫先起一个分支装上用 ESLint 插件跑一遍全量检查。你很快会看清两件事——存量代码里藏着多少渲染期副作用以及删掉那几百个手动缓存之后项目到底会不会散架。至少在我们团队这次编译优化带来的不只是单点性能提升而是把大家从有没有漏加 useCallback的焦虑里彻底解放了出来。这种心智负担的减轻才是编译器真正划时代的地方。