React 19稳定版发布已经有一段时间了，我们团队也在几个项目里完成了升级和实战。这篇文章想分享一下在实际项目中使用React 19遇到的各种坑，以及对应的解决方案。

升级React 19不是改个版本号那么简单，它带来了很多新特性和行为变化，如果不了解这些变化，很容易在实际开发中踩坑。我们团队在升级过程中踩了不少坑，有些坑还挺隐蔽的，花了不少时间才找到原因。

这篇文章记录的都是真实项目中遇到的问题，不是文档里的理论知识。希望这些经验能帮大家在升级React 19的时候少走弯路。

Actions的坑：表单提交不是想象的那样

React 19引入了Actions的概念，把异步操作和状态管理整合到了一起。最典型的应用就是表单处理，用useActionState或者直接给form的action传一个函数，React会自动管理pending状态和错误状态。

看起来很美好，但实际用起来有几个坑。

第一个坑是Actions里的状态更新不是立即生效的。在Action函数里调用setState，你不能在同一个函数里立即拿到更新后的状态，因为React会把状态更新批量处理，等Action执行完之后才会重新渲染。如果你在Action里依赖更新后的状态做判断，就会出问题。

解决方案是不要在Action里依赖state做判断，而是用局部变量或者参数来传递需要的值。把需要的数据作为参数传给Action函数，而不是从state里读。

第二个坑是form的action和onSubmit的区别。很多人习惯用onSubmit来处理表单提交，在React 19里如果同时用了action和onSubmit，会有一些行为上的差异。action是React推荐的方式，它会自动管理pending状态，但onSubmit里的preventDefault和action的行为可能冲突。

我们的做法是要么完全用action，要么完全用onSubmit，不要混用。如果用action，就不要在onSubmit里做逻辑处理，把逻辑都放到action函数里。

第三个坑是Action的错误处理。React 19的useActionState返回了error状态，但这个error只能捕获Action函数里抛出的同步错误。如果Action里有异步操作，比如fetch请求失败，需要手动把错误信息通过返回值或者setState传出来，不能直接throw。

我们的做法是在Action里用try-catch包裹异步操作，把错误信息作为返回值返回，然后在组件里根据返回值显示错误提示。不要依赖React自动捕获异步错误。

use()的坑：不是所有地方都能用

React 19引入了use()这个新API，可以在渲染过程中读取Promise和Context。这个API看起来很强大，但实际用起来有不少限制。

第一个坑是use()不能在条件语句和循环里调用。和Hooks一样，use()也必须在组件的顶层调用，不能放在if、for、while里面。如果在条件里调用use()，React会报错。

这个限制和Hooks的规则一样，但很多人因为use()是新API就忽略了这个规则，结果踩坑。记住，所有以use开头的Hooks，都必须在顶层调用。

第二个坑是use()读取Promise的时候，会触发Suspense。如果Promise还没resolve，组件会挂起，需要外面包一层Suspense。很多人用use()的时候忘记包Suspense，结果页面白屏或者报错。

我们的做法是，凡是用use()读取Promise的地方，外面都包一层Suspense，并提供fallback加载状态。不要假设Promise已经resolve了。

第三个坑是use()读取Context和useContext的区别。React 19里use()可以读取Context，而且支持在条件里读取（因为Context不是Promise，不会挂起）。但如果你同时用了use()和useContext读取同一个Context，要注意它们的行为是一致的，没有本质区别。

我们的建议是，读取Context还是用useContext，因为它更明确，工具链支持也更好。use()主要用来读取Promise，不要用它来替代useContext。

React Compiler的坑：不是开了就万事大吉

React 19配套的React Compiler是一个大杀器，它能自动优化重新渲染，不用再手写useMemo和useCallback。但实际用起来也有坑。

第一个坑是Compiler不是所有代码都能优化。它有一些限制，比如不能优化有副作用的代码、不能优化依赖外部可变变量的代码、不能优化某些复杂的模式。如果你的代码不符合Compiler的要求，它会跳过优化，甚至可能报错。

我们的做法是开启Compiler的严格模式，让它在遇到不能优化的代码时给出警告。然后根据警告信息逐步修改代码，让更多的组件能被优化。不要以为开了Compiler就万事大吉了。

第二个坑是Compiler可能改变组件的行为。因为Compiler会自动缓存计算结果，如果你的代码依赖引用相等性（比如useEffect的依赖是一个对象），Compiler的缓存可能导致effect不触发或者触发时机不对。

我们遇到过一个问题：一个组件的useEffect依赖一个props对象，Compiler自动缓存了这个对象，导致props变化的时候effect没有触发。解决方案是把依赖拆成基本类型，或者用useEffect的依赖数组明确指定需要监听的字段。

第三个坑是Compiler和第三方库的兼容性。有些第三方库的代码不符合Compiler的要求，会导致Compiler报错或者跳过整个文件的优化。特别是一些老的库，可能用了很多可变模式和副作用。

我们的做法是在Compiler的配置里排除第三方库的目录，只优化自己的业务代码。等第三方库适配了Compiler之后再逐步放开。

并发特性的坑：不是所有场景都适合

React 19的并发特性（Concurrent Features）更加稳定了，useTransition、useDeferredValue这些API在实际项目中用得越来越多。但并发特性不是银弹，用不好反而会出问题。

第一个坑是useTransition里的更新优先级问题。useTransition里的状态更新是低优先级的，如果在transition里更新了一个状态，同时在外面又更新了同一个状态，外面的高优先级更新会中断transition里的更新。这可能导致状态不一致。

我们遇到过一个搜索框的问题：用户输入的时候，用useTransition来延迟更新搜索结果，但如果用户快速输入，transition不断被中断，导致搜索结果一直不更新。解决方案是加一个防抖，或者用useDeferredValue来处理延迟更新。

第二个坑是并发渲染下的ref问题。在并发模式下，组件可能被渲染多次，ref的回调可能被调用多次，而且顺序可能和预期不一样。如果在ref回调里做了副作用，可能会出问题。

我们的做法是不要在ref回调里做副作用，只用来保存DOM引用。副作用放到useEffect里处理，因为useEffect在提交阶段才执行，不会有并发问题。

第三个坑是Suspense的竞态条件。在并发模式下，Suspense的fallback可能会闪烁，特别是数据加载很快的时候。如果Promise在很短的时间内就resolve了，Suspense可能先显示fallback再显示内容，造成闪烁。

React 19提供了一些方案来避免这个问题，比如延迟显示fallback。我们的做法是给Suspense加一个最小显示时间，或者用CSS过渡来平滑切换，避免突兀的闪烁。

服务端组件的坑：客户端和服务端的边界

如果你的项目用了Next.js或者其他支持React Server Components的框架，升级React 19的时候还要注意服务端组件的坑。

第一个坑是客户端组件不能直接导入服务端组件的逻辑。很多人习惯把工具函数和常量放在一个文件里，然后在客户端和服务端组件里都导入。但如果这个文件里有服务端特有的代码（比如读取数据库），在客户端导入就会报错。

我们的做法是把共享的纯函数和常量单独放在一个文件里，明确标注为可以在两端使用的。服务端特有的逻辑放在服务端目录里，不要被客户端组件导入。

第二个坑是"use client"指令的位置。React 19对"use client"指令的检查更严格了，它必须在文件的最顶部，前面不能有任何其他代码（除了注释）。如果文件顶部有import语句或者其他代码，"use client"不会生效。

我们遇到过一个问题：一个文件顶部有一行注释，然后是"use client"，结果这个指令没有被识别，组件被当成了服务端组件，导致浏览器里的API调用报错。解决方案是把"use client"放在文件的第一行，前面不要有任何内容。

第三个坑是服务端组件不能用客户端Hooks。这个是基本规则，但实际开发中很容易忘记。比如在服务端组件里用了useState、useEffect、useRouter等客户端Hooks，就会报错。

我们的做法是在写组件的时候先想清楚这个组件是服务端还是客户端的。需要交互和状态的就加"use client"，纯展示和数据获取的就用服务端组件。不要在服务端组件里写交互逻辑。

样式和DOM的变化

React 19对DOM和样式的处理也有一些变化，这些变化虽然不大，但也可能踩坑。

第一个变化是style属性支持传入数组了。以前style只能传一个对象，现在可以传一个对象数组，React会自动合并。但如果你用了一些老的第三方库，它们可能还在期望style是一个对象，传数组进去可能会出问题。

我们的建议是暂时不要在第三方组件上用数组style，等库适配了再用。自己写的组件可以放心用，确实很方便。

第二个变化是ref可以作为props传递了。React 19里ref不再是特殊的prop，可以像普通props一样传递和接收。这意味着forwardRef可能不再需要了。但如果你在老的代码里用了forwardRef，和新的ref传递方式混用，可能会有问题。

我们的做法是新代码直接用ref作为props，老代码逐步迁移。不要在同一个组件里同时用forwardRef和ref props，选择一种方式就好。

第三个变化是表单元素的defaultValue和value的行为。React 19对受控和非受控表单的处理有一些调整，特别是checkbox和radio的checked属性。如果你的表单逻辑依赖旧的行为，升级后可能会出现状态不同步的问题。

我们的做法是升级后全面测试表单功能，特别是checkbox和radio的联动。发现问题就调整成React 19推荐的写法，不要依赖旧的边缘行为。

升级建议

最后给大家一些升级React 19的建议。

第一，先读官方升级指南。React 19的官方文档写得很详细，列出了所有的破坏性变更和新特性。升级前一定要通读一遍，了解哪些东西变了，不要凭印象升级。

第二，逐步升级，不要一步到位。可以先在一个小项目或者一个模块里升级React 19，跑通了再推广到整个项目。不要一上来就把整个大项目升级了，出了问题不好定位。

第三，充分测试。特别是表单、并发渲染、Suspense相关的功能，要重点测试。React 19的很多变化是行为层面的，语法不报错但行为可能变了，只有测试才能发现。

第四，关注控制台警告。React 19会对一些废弃的API和不推荐的用法给出警告，这些警告往往就是潜在的坑。看到警告就及时修复，不要忽略。

第五，不要急于用所有新特性。React 19的新特性很多，但不是每个都适合你的项目。先把基础的升级做好，稳定运行之后再逐步引入新特性。不要为了用新特性而用新特性。

写在最后

React 19是一个重要的版本更新，带来了很多令人兴奋的新特性。但升级的过程中确实有不少坑需要踩，这篇文章记录的只是我们团队遇到的一部分。

每个项目的情况不一样，遇到的坑也不一样。最重要的是保持学习的心态，遇到问题仔细排查，多参考官方文档和社区经验，总能找到解决方案。

React的生态一直在发展，新的特性和最佳实践也在不断涌现。作为前端开发者，我们需要持续学习，跟上技术的发展。但同时也要保持理性，不要盲目追新，选择适合自己项目的技术方案。

最后用一句话来结束这篇文章："技术升级不是目的，解决问题才是。新特性再好，也要服务于实际需求。"

愿每一个前端开发者，都能在React的世界里写出优雅、高效、可维护的代码。