React 19 最新升级官方指南：值得注意的变化

给前端以福利，给编程以复利。大家好，我是大家的林语冰。

00. 观前须知

React 团队爆料最新主版本升级 React 19 Beta（公测版）已经正式上线 npm，想要提前体验最新版本的 React 发烧友可以参考这份 React 官方博客的升级指南。

为了辅助你顺利升级到 React 19，我们发布了与 React 18.2 等价的 react@18.3 版本，但添加了废弃 API 的相关警告，以及 React 19 所需的其他变更。

粉丝请注意，React 19 公测版是 React 19 主版本的前戏。React 发烧友请先升级到 React 18.3，然后耐心等待 React 19 稳定版，切勿操之过急，否则后果自负。

在本文中，我们将科普将库升级到 React 19 beta 值得注意的变化：

• 新的弃用功能
• 显著更改
• TS 更改

免责声明

本文属于是语冰的直男翻译了属于是，略有删改，仅供粉丝参考。英文原味版请传送 React 19 Beta Upgrade Guide。

01. 新的已弃用功能

01-1. 已弃用：element.ref

React 19 支持 ref 作为 prop，因此我们弃用 element.ref 来代替 element.props.ref。

01-2. 已弃用：react-test-renderer

我们弃用了 react-test-renderer，因为它实现了自己的渲染器环境，这不匹配用户使用的环境，促进了测试实现细节，且依赖 React 内部的内省。

测试渲染器是在有 React Testing Library 等更可行的测试策略之前创建的，我们现在建议使用现代测试库取而代之。

在 React 19 中，react-test-renderer 打印了弃用警告，且已切换到并发渲染。我们建议将你的测试迁移到 @testing-library/react 或 @testing-library/react-native，获取现代化且良好支持的测试体验。

02. 值得注意的变化

02-1. 严格模式更改

在开发中以严格模式二次渲染时，useMemo 和 useCallback 将在二次渲染期间复用首次渲染的记忆化结果。兼容严格模式的组件不应注意到这个行为差异。

与所有严格模式行为一样，这些功能旨在在开发过程中主动发现组件中的 bug，这样你可以在将它们交付生产之前修复它们。

举个栗子，在开发过程中，严格模式将在初始挂载时两次执行 ref 回调函数，模拟挂载的组件被 Suspense 后备方案替换时发生的情况。

02-2. UMD 构建已删除

UMD 过去被广泛使用，作为一种无需构建步骤即可加载 React 的便捷方式。现在，有一些现代替代方案可以将模块作为脚本加载到 HTML 文档中。

从 React 19 开始，React 将不再生成 UMD 构建，降低其测试和发布过程的复杂性。

要使用 script 标记加载 React 19，我们建议使用基于 ESM 的 CDN，比如 esm.sh。

<script type="module">
  import React from "https://esm.sh/react@19/?dev"
  import ReactDOMClient from "https://esm.sh/react-dom@19/client?dev"
  ...
</script>

02-3. 依赖 React 内部的库可能会阻碍升级

React 19 包含了对 React 内部结构的更改，这些更改可能会影响那些忽略我们不使用 SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED 等内部结构的请求的库。为了改良 React 19，这些更改势在必行，且不会破坏遵循我们指南的库。

根据我们的版本控制政策，这些更新未列为破坏性更改，且我们不包含有关如何升级它们的文档。建议删除任何依赖内部的代码。

为了反映使用内部结构的影响，我们将 SECRET_INTERNALS 后缀重命名为：_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE。

将来，我们将更积极地阻止从 React 访问内部组件，阻止使用并确保用户不会被阻碍升级。

03. TS 更改

03-1. 删除了已弃用的 TS 类型

我们根据 React 19 中删除的 API 清理了 TS 类型。一些删除的类型已移至更相关的包中，而其他类型则不再需要描述 React 的行为。

我们发布了 types-react-codemod 来迁移大多数类型相关的破坏性更改：

npx types-react-codemod@latest preset-19 ./path-to-app

如果你对 element.props 有很多不健全的访问权限，你可以运行这个额外的 codemod：

npx types-react-codemod@latest react-element-default-any-props ./path-to-your-react-ts-files

03-2. 需要的 ref 清理函数

此更改包含在 react-19 codemod 预设中，作为 no-implicit-ref-callback-return。

由于 ref 清理函数的引入，从 ref 回调函数返回任何其他内容现在都将被 TS 拒绝。解决方法通常是停止使用隐式返回：

- <div ref={current => (instance = current)} />
+ <div ref={current => {instance = current}} />

原始代码返回 HTMLDivElement 的实例，TS 不知道这是否应该是一个清理函数。

03-3. useRef 需要一个参数

此更改包含在 react-19 codemod 预设中，作为 refobject-defaults。

长期以来对 TS 和 React 工作方式的抱怨是 useRef。我们更改了类型，因此 useRef 现在需要参数。这显著简化了其类型签名。现在它的行为更像 createContext。

// @ts-expect-error：期望一个参数但没有
useRef()
// 类型合法
useRef(undefined)
// @ts-expect-error：期望一个参数但没有
createContext()
// 类型合法
createContext(undefined)

现在这也意味着所有 ref 都是可变的。你将不再遭遇无法更改 ref 的问题，因为你使用 null 初始化了它：

const ref = useRef<number>(null)

// 无法赋值给 current，
// 因为它是一个只读属性
ref.current = 1

MutableRef 现已弃用，取而代之的是 RefObject 类型，useRef 将始终返回：

interface RefObject<T> {
  current: T
}

declare function useRef<T>: RefObject<T>

useRef 仍具有自动返回 RefObject<T | null> 的 useRef<T>(null) 便捷重载。为了简化由于 useRef 所需参数而导致的迁移，添加了 useRef(undefined) 的便捷重载，它会自动返回 RefObject<T | undefined>。

03-4. 对 ReactElement TS 类型的更改

此更改包含在 react-element-default-any-props codemod 中。

如果元素类型为 ReactElement，React 元素的 props 现在默认为 unknown 而不是 any。如果你将类型参数传递给 ReactElement，这不会影响到你：

type Example2 = ReactElement<{ id: string }>['props']
//   ^? { id: string }

但如果你依赖默认值，你现在必须处理 unknown：

type Example = ReactElement['props']
//   ^? 切换前是 any，现在是 unknown

当且仅当你有大量依赖元素属性的不健全访问的过时代码时才需要它。元素内省仅作为逃生通道存在，你应该通过显式 any 明确表明你的 props 访问不健全。

03-5. TS 中的 JSX 命名空间

此更改包含在 react-19 codemod 预设中，作为 scoped-jsx。

一个长期的请求是从我们的类型中删除全局 JSX 命名空间，以支持 React.JSX。这有助于防止全局类型污染，防止利用 JSX 的不同 UI 库之间发生冲突。

现在，你需要将 JSX 命名空间的模块扩展包装在 declare module ”...” 中：

// global.d.ts
+ declare module "react" {
    namespace JSX {
      interface IntrinsicElements {
        "my-element": {
          myElementProps: string;
        };
      }
    }
+ }

确切的模块说明符取决于你在 tsconfig.json 的 compilerOptions 中指定的 JSX 运行时：

• 对于 "jsx": "react-jsx"，它将是 react/jsx-runtime。
• 对于 "jsx": "react-jsxdev"，它将是 react/jsx-dev-runtime。
• 对于 "jsx": "react" 和 "jsx": "preserve"，它将是 react。

03-6. 更好的 useReducer typings

useReducer 现在改进了类型推断。

然而，这需要一个破坏性更改，其中 useReducer 不接受完整的 reducer 类型作为类型参数，而是要么不需要任何类型且依赖上下文类型，要么需要 state 和 action 类型。

新的最佳实践是不要将类型参数传递给 useReducer。

- useReducer<React.Reducer<State, Action>>(reducer)
+ useReducer(reducer)

这在极端情况下可能行不通，你可以通过在元组中传入 Action 来显式键入 state 和 action：

- useReducer<React.Reducer<State, Action>>(reducer)
+ useReducer<State, [Action]>(reducer)

如果你内联定义 reducer，我们鼓励改为注解函数参数：

- useReducer<React.Reducer<State, Action>>((state, action) => state)
+ useReducer((state: State, action: Action) => state)

如果你将 reducer 移到 useReducer 调用之外，你也必须执行以下操作：

const reducer = (state: State, action: Action) => state

参考文献

1. React：react.dev
2. Upgrade Guide：react.dev/blog/2024/0…
3. facebook/react：github.com/facebook/re…

粉丝互动

本期话题是：如何评价 React 19 公测版的技术细节？你可以在本文下方自由言论，文明科普。

欢迎持续关注“前端俱乐部”，给前端以福利，给编程以复利。

坚持阅读的小伙伴可以给自己点赞！谢谢大家的点赞，掰掰~