React Native 的新架构

了解 React Native 的“新架构”，以及如何以及为什么迁移到它。

信息 SDK 55 及更高版本完全运行在新架构上。新架构始终启用且无法禁用。如果需要使用旧架构，请使用 SDK 54 或更早版本。

新架构是我们用来描述 React Native 内部彻底重构的一个名称。它也用于解决在 Meta 和其他公司多年生产环境使用中发现的原始 React Native 架构的限制。

🌐 The New Architecture is a name that we use to describe a complete refactoring of the internals of React Native. It is also used to solve limitations of the original React Native architecture discovered over years of usage in production at Meta and other companies.

在本指南中，我们今天将讨论如何在 Expo 项目中使用新架构。

🌐 In this guide, we'll talk about how to use the New Architecture in Expo projects today.

新架构已推出

Meta 的 React Native 团队发布的一篇博客文章，概述了新架构的特性以及构建它的动机。

React Native 0.82 - 新纪元

React Native 0.82 是第一个完全运行在新架构上的版本。SDK 55 使用 React Native 0.83，它继承了这一行为。

为什么要迁移到新架构？

新架构是 React Native 的现在与未来。从 React Native 0.82 开始，新架构将始终启用，无法禁用。SDK 55 使用 React Native 0.83，其继承了这一行为。传统架构已于 2025 年 6 月冻结，这意味着不再为其开发新功能或修复漏洞。

新的 React 和 React Native 功能仅适用于新架构。例如，新架构包括对 Suspense 的全面支持和新的样式功能，这些在旧架构中并未实现。许多流行的库现在仅支持新架构。

如果你使用的是 SDK 54 或更早版本，你仍然可以通过将 newArchEnabled 设置为 false 来使用传统架构。不过，在升级到 SDK 55 或更高版本之前，你需要迁移到新架构。

Expo 工具与新架构

🌐 Expo tools and the New Architecture

截至 SDK 53，Expo SDK 中的所有 expo-* 包都支持新架构（包括无桥接）。了解已知问题。

🌐 As of SDK 53, all expo-* packages in the Expo SDK support the New Architecture (including bridgeless). Learn more about known issues.

此外，所有使用 Expo 模块 API 编写的模块默认都支持新架构！所以如果你使用该 API 构建了自己的原生模块，使用它们与新架构时无需额外操作。

🌐 Additionally, all modules written using the Expo Modules API support the New Architecture by default! So if you have built your own native modules using this API, no additional work is needed to use them with the New Architecture.

截至2026年1月，大约83%使用EAS Build构建的SDK 54项目采用了新架构。

第三方库与新架构

🌐 Third-party libraries and the New Architecture

许多最流行库的兼容性状态都在 React Native Directory 上进行跟踪（了解更多第三方库的已知问题）。我们在 Expo Doctor 中内置了工具，以与 React Native Directory 集成，帮助你验证依赖，这样你就能快速了解哪些库已经不再维护，以及哪些库与新架构不兼容或未经测试。

🌐 The compatibility status of many of the most popular libraries is tracked on React Native Directory (learn more about known issues in third-party libraries). We've built tooling into Expo Doctor to integrate with React Native Directory to help you validate your dependencies, so you can quickly learn which libraries are unmaintained and which incompatible or untested with the New Architecture.

使用 React Native 目录验证你的依赖

🌐 Validate your dependencies with React Native Directory

运行 npx expo-doctor 来检查你的依赖是否与 React Native 目录中的数据一致。

🌐 Run npx expo-doctor to check your dependencies against the data in React Native Directory.

Terminal

- npx expo-doctor@latest

你可以在 package.json 文件中配置 React Native 目录检查。例如，如果你想从验证中排除某个包：

🌐 You can configure the React Native Directory check in your package.json file. For example, if you would like to exclude a package from validation:

package.json

{
  "expo": {
    "doctor": {
      "reactNativeDirectoryCheck": {
        "exclude": ["react-redux"]
      }
    }
  }
}

查看所有可用选项

已启用：如果为 true，检查将会在 React Native 目录中缺少任何包时发出警告。将其设置为 false 可禁用此行为。在 SDK 52 及更高版本中，默认设置为 true，否则默认设置为 false。你还可以使用 EXPO_DOCTOR_ENABLE_DIRECTORY_CHECK 环境变量覆盖此设置（0 表示 false，1 表示 true）。
排除：列出你想从检查中排除的任何软件包。支持精确的软件包名称和正则表达式模式。例如，["exact-package", "/or-a-regex-.*/"]。
listUnknownPackages：默认情况下，如果 React Native 目录中缺少任何包，检查会发出警告。将此设置为 false 可禁用此行为。

使用新架构初始化一个新项目

🌐 Initialize a new project with the New Architecture

从 SDK 52 开始，所有新项目默认将启用新架构进行初始化。

Terminal

- npx create-expo-app@latest

在现有项目中启用新架构

🌐 Enable the New Architecture in an existing project

新架构在 SDK 55 及更高版本中始终启用。没有关闭它的选项。SDK 55 使用 React Native 0.83。React Native 0.82 是第一个移除禁用新架构选项的版本，这适用于所有后续版本。

如果你之前在应用配置中使用了 newArchEnabled: false，此设置将被忽略。请从配置中移除它以避免混淆。

在 SDK 53 和 SDK 54 中，新架构默认已启用。如果你曾明确禁用它，请删除该配置以启用。

信息 SDK 54 是可以禁用新架构的最后一个 SDK 版本。

我们建议升级到 SDK 53，以确保你的应用能够利用所有最新的新架构相关修复和库以及 React Native 本身的改进。如果你想先在 SDK 52 上尝试，请按照以下说明操作。

要在 Android 和 iOS 上启用它，请在应用配置的 expo 对象根部使用 newArchEnabled。你也可以通过设置，例如 "android": { "newArchEnabled": true }，选择性地只在单个平台上启用它。

app.json

{
  "expo": {
    "newArchEnabled": true
  }
}

创建新版本：

Terminal

# Run a clean prebuild and start a local build, if you like

- npx expo prebuild --clean && npx expo run:android

# Run a build with EAS if you prefer

- eas build -p android

Terminal

# Run a clean prebuild and start a local build, if you like

- npx expo prebuild --clean && npx expo run:ios

# Run a build with EAS if you prefer

- eas build -p ios

如果构建成功，你现在将使用新架构运行你的应用！根据你使用的原生模块，你的应用可能会立即正常运行。

现在你可以在你的应用中随意点击并进行测试。对于大多数非简单应用，你可能会遇到一些问题，比如一些原生视图尚未为新架构实现。你遇到的许多问题都是可解决的，可以通过一些配置或代码修改来解决。我们建议阅读下面的故障排除部分以获取更多信息。

我们建议升级到 SDK 54 或 SDK 55。SDK 51 已经明显过时，并且旧架构已被冻结，这意味着它不会收到新的功能或错误修复。虽然可以在 SDK 51 中启用新架构，但你可能会遇到在较新版本中已解决的各种问题。要启用它，你需要安装 expo-build-properties 插件并在目标平台上设置 newArchEnabled。

你是在一个空的 React Native 应用中启用新架构吗？

如果你使用的是 Expo SDK 53 或更高版本，新架构默认启用。对于 SDK 55 及更高版本，新架构始终启用，无法禁用。以下说明适用于 SDK 52 及更早版本的项目。

🌐 If you are using Expo SDK 53 or later, the New Architecture is enabled by default. For SDK 55 and later, the New Architecture is always enabled and cannot be disabled. The following instructions apply to SDK 52 and earlier projects.

Android：在 gradle.properties 文件中设置 newArchEnabled=true。
iOS：如果你的项目中有 Podfile.properties.json 文件（该文件由 npx create-expo-app 或 npx expo prebuild 创建），你可以通过在 Podfile.properties.json 文件中将 newArchEnabled 属性设置为 "true" 来启用新架构。否则，请参考 React Native 新架构工作组的 “为应用启用新架构” 部分。

在现有项目中禁用新架构

🌐 Disable the New Architecture in an existing project

警告 SDK 55 及更高版本不支持禁用新架构。 SDK 55 使用 React Native 0.83。从 React Native 0.82 开始，禁用新架构的选项已被移除，因此将 newArchEnabled 设置为 false 不会生效。如果需要使用旧架构，请使用 SDK 54 或更早版本。

信息 Expo Go 仅支持新架构。

在 SDK 54 及更早版本中，你可以通过在应用配置中将 newArchEnabled 属性设置为 false 来选择退出新架构，并创建一个开发构建。

🌐 On SDK 54 and earlier, you can opt out of the New Architecture by setting the newArchEnabled property to false in app config and create a development build.

app.json

{
  "expo": {
    "newArchEnabled": false
  }
}

你是否在一个原生 React Native 应用（SDK 54 及更早版本）中禁用了新架构？

Android：在 gradle.properties 文件中设置 newArchEnabled=false。
iOS：如果你的项目中有 Podfile.properties.json 文件（该文件由 npx create-expo-app 或 npx expo prebuild 创建），你可以通过在 Podfile.properties.json 文件中将 newArchEnabled 属性设置为 "false" 来禁用新架构。否则，请参考 React Native 新架构工作组的 “为应用启用新架构” 部分。

故障排除

🌐 Troubleshooting

Meta 和 Expo 正在努力使新架构成为所有新应用的默认选项，并确保迁移现有应用尽可能简单。然而，新架构不仅仅是一个名称——React Native 的许多内部结构已经从头开始重新设计和重建。因此，在你的应用中启用新架构时，可能会遇到一些问题。以下是一些解决这些问题的建议。

🌐 Meta and Expo are working toward making the New Architecture the default for all new apps and ensuring it is as easy as possible to migrate existing apps. However, the New Architecture isn't just a name — many of the internals of React Native has been re-architected and rebuilt from the ground up. As a result, you may encounter issues when enabling the New Architecture in your app. The following is some advice for troubleshooting these issues.

即使我使用的一些库不受支持，我还能尝试新架构吗？

即使你使用的一些库不被支持，你仍然可以在应用中尝试新架构，但这需要暂时移除那些库。在你的代码仓库中创建一个新分支，并移除任何不兼容的库，直到你的应用可以运行为止。这将让你清楚哪些库在完全迁移到新架构之前还需要进行调整。我们建议在那些库的仓库中创建 issue 或 pull request，帮助它们实现与新架构的兼容。或者，你也可以切换到与新架构兼容的其他库。请参考 React Native 目录来查找兼容的库。

🌐 You may be able to try the New Architecture in your app even if some of the libraries you use aren't supported, but it will require temporarily removing those libraries. Create a new branch in your repository and remove any of the libraries that aren't compatible until your app is running. This will give you a good idea of what libraries still need work before you can fully migrate to the New Architecture. We recommend creating issues or pull requests on those libraries' repositories to help them become compatible with the New Architecture. Alternatively, you could switch to other libraries that are compatible with the New Architecture. Refer to React Native Directory to find compatible libraries.

React Native 中已知的问题

请参考 React Native GitHub 仓库中标记为“Type: New Architecture”的问题。

🌐 Refer to the issues labeled with "Type: New Architecture" on the React Native GitHub repository.

Expo 库中的已知问题

在 Expo 库中没有已知特定于新架构的问题。

🌐 There are no known issues specific to the New Architecture in Expo libraries.

第三方库中的已知问题

自 React Native 0.74 以来，默认启用了各种互操作层。这使得许多为旧架构构建的库可以在新架构上无修改地工作。然而，互操作并不完美，一些库仍需要更新。最有可能需要更新的库是那些包含或依赖第三方原生代码的库。了解有关新架构中库支持的更多信息。

🌐 Since React Native 0.74, there are various Interop Layers enabled by default. This allows many libraries built for the old architecture to work on the New Architecture without any changes. However, the interop is not perfect and some libraries will need to be updated. The libraries that are most likely to require updates are those that ship or depend on third-party native code. Learn more about library support in the New Architecture.

请参阅 React Native Directory 获取更完整的库列表及其与新架构的兼容性。以下库在 Expo 应用中很受欢迎，但已知不兼容：

🌐 Refer to React Native Directory a more complete list of libraries and their compatibility with the New Architecture. The following libraries were found to be popular among Expo apps and are known to be incompatible:

以下是一些在 Expo 应用中流行的库已知问题。

🌐 The following are known issues with libraries that are popular among Expo apps.

react-native-maps：版本 1.20.x，是 SDK 53 的默认版本，支持带中间层的新架构，并且大多数功能都能良好运行。以新架构为优先的版本可在 1.21.0 版本中使用，目前仍在稳定中。我们鼓励你在应用中进行测试，报告发现的问题，并关注 GitHub 上的讨论。我们也在研究另一种方法，可能会提供更平滑的迁移路径，它依赖于中间层而不是重写模块。值得一提的是，如果你的应用可以强制使用 iOS 17 以上的最低版本，或者不需要在 iOS 上支持地图，那么可以考虑使用expo-maps来代替。
@stripe/react-native：从版本 0.45.0 开始支持新架构，该版本是 SDK 53 的默认版本。
@react-native-community/masked-view：请改用 @react-native-masked-view/masked-view。
@react-native-community/clipboard：请改用 @react-native-clipboard/clipboard。
rn-fetch-blob：请改用 react-native-blob-util。
react-native-fs：请改用 expo-file-system 或 react-native-fs 的一个分支。
react-native-geolocation-service：请使用 expo-location 替代。
react-native-datepicker：请改用 react-native-date-picker 或 @react-native-community/datetimepicker。

启用新架构后，我的构建失败了

这并不完全令人惊讶！并不是所有的库都已经兼容，在某些情况下，兼容性只是最近才加入的，因此你需要确保将你的库更新到最新版本。查看日志以确定哪个库不兼容。此外，运行 npx expo-doctor@latest 来检查你的依赖与 React Native 目录中的数据是否匹配。

🌐 This isn't entirely surprising! Not all libraries are compatible yet, and in some cases compatibility was only recently added and so you will want to ensure you update your libraries to their latest versions. Read the logs to determine which library is incompatible. Also, run npx expo-doctor@latest to check your dependencies against the data in React Native Directory.

当你使用库的最新版本且不兼容时，请将遇到的任何问题报告到相应的 GitHub 仓库。创建一个最小可重现示例并将问题报告给库的作者。如果你认为问题来源于 React Native 本身，而不是某个库，请将其报告给 React Native 团队（同样，提供一个最小可重现示例）。

🌐 When you are using the latest version of a library and it is not compatible, report any issues you encounter to the respective GitHub repository. Create a minimal reproducible example and report the issue to the library author. If you believe the issue originates in React Native itself, rather than a library, report it to the React Native team (again, with a minimal reproducible example).