新架构

了解 React Native 的 "新架构" 以及如何以及为何迁移到它。

我们建议使用 SDK 51 或更高版本以获得最佳的新架构体验。

新架构是我们用来描述 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.

要了解有关新架构背后的想法和动机的更多信息，我们推荐以下资源：

¥To learn more about the ideas and motivations behind the New Architecture, we recommend the following resources:

新架构简介

探索与新架构相关的各种主题的起点。

为何采用新架构

新架构背后动机的高层次概述。

为什么要投资迁移到新架构？

¥Why invest in migrating to the New Architecture?

新架构是 React Native 的未来 - 然而，对于许多应用来说，今天的迁移可能不会带来很多直接的好处。你可能希望将迁移到新架构视为对应用未来的投资，而不是立即改进应用的方法。

¥The New Architecture is the future of React Native — yet, for many apps, there may not be many immediate benefits to migrating today. You may want to think of migrating to the New Architecture as an investment in the future of your app, rather than as a way to immediately improve your app.

新架构带来的变化解决了原始实现的技术债务，并释放了解决 React Native 中长期存在的问题的可能性，例如与同步原生 API（例如 UITableView）的互操作性，并为并发反应支持铺平了道路。

¥The changes that come with the New Architecture address the technical debt of the original implementation and unlock possibilities for solving long-standing issues in React Native, such as interoperability with synchronous native APIs (for example, UITableView), and pave the way for concurrent React support.

Expo 工具和新架构

¥Expo tools and the New Architecture

截至 SDK 51，Expo SDK 中的几乎所有 expo-* 包都支持新架构（包括 bridgeless）。了解有关已知问题的更多信息。

¥As of SDK 51, nearly 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.

第三方库和新架构

¥Third-party libraries and the New Architecture

许多最流行的库的兼容性状态在 React Native 目录 (检查项目文件) 上进行跟踪。我们在 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 Directory 验证你的依赖

¥Validate your dependencies with React Native Directory

要根据 React Native 目录中的数据验证你的依赖，你可以使用 npx expo-doctor。要启用此检查，请将以下内容添加到你的 package.json 文件中：

¥To validate your dependencies against the data in React Native Directory, you can use npx expo-doctor. To enable this check, add the following to your package.json file:

package.json

{
  "expo": {
    "doctor": {
      "reactNativeDirectoryCheck": {
        "enabled": true
      }
    }
  }
}

然后运行 npx expo-doctor 以根据 React Native 目录中的数据检查你的依赖。

¥Then run npx expo-doctor to check your dependencies against the data in React Native Directory.

Terminal

- npx expo-doctor@latest

See all available options

已启用：默认情况下，如果 React Native 目录中缺少任何包，检查将发出警告。将其设置为 false 以禁用此行为。

¥enabled: By default, the check will warn if any packages are missing from React Native Directory. Set this to false to disable this behavior.
排除：列出你想要从检查中排除的任何包。支持精确的包名称和正则表达式模式，例如：["exact-package", "/or-a-regex-.*/"]。

¥exclude: List any packages you want to exclude from the check. Supports exact package names and regex patterns, eg: ["exact-package", "/or-a-regex-.*/"].
listUnknownPackages：默认情况下，如果 React Native 目录中缺少任何包，检查将发出警告。将其设置为 false 以禁用此行为。

¥listUnknownPackages: By default, the check will warn if any packages are missing from React Native Directory. Set this to false to disable this behavior.

Want to run this check once without adding it to your package.json file?

在运行 npx expo-doctor 之前设置环境变量 EXPO_DOCTOR_ENABLE_DIRECTORY_CHECK=1。

¥Set the environment variable EXPO_DOCTOR_ENABLE_DIRECTORY_CHECK=1 before running npx expo-doctor.

Terminal

- EXPO_DOCTOR_ENABLE_DIRECTORY_CHECK=1 npx expo-doctor@latest

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

¥Initialize a new project with the New Architecture

开始使用新架构的最简单方法是在创建新项目时使用 with-new-arch 模板：

¥The easiest way to get started with the New Architecture is to use the with-new-arch template when creating a new project:

Terminal

- npx create-expo-app@latest -e with-new-arch

在现有项目中启用新架构

¥Enable the New Architecture in an existing project

你可以使用 expo-build-properties 配置插件在应用中启用新架构：

¥You can enable the New Architecture in your app using the expo-build-properties config plugin:

安装 expo-build-properties：

¥Install expo-build-properties:

Terminal

- npx expo install expo-build-properties

在目标平台上设置 newArchEnabled：

¥Set newArchEnabled on target platforms:

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "ios": {
            "newArchEnabled": true
          },
          "android": {
            "newArchEnabled": true
          }
        }
      ]
    ]
  }
}

运行 prebuild 命令并编译你的项目：

¥Run the prebuild command and compile your project:

Terminal

- npx expo prebuild --clean

- npx expo run:android

- eas build -p android

Terminal

- npx expo prebuild --clean

- npx expo run:ios

- eas build -p ios

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

¥If the build succeeds, you will now be running your app with the New Architecture! Depending on the native modules you use, your app may work properly immediately.

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

¥Now you can tap around your app and test it out. For most non-trivial apps, you're likely to encounter some issues, such as missing native views that haven't been implemented for the New Architecture yet. Many of the issues you encounter are actionable and can be resolved with some configuration or code changes. We recommend reading Troubleshooting sections below for more information.

Are you enabling the New Architecture in a bare React Native app?

安卓：在 gradle.properties 文件中设置 newArchEnabled=true。

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

¥iOS: If your project has a Podfile.properties.json file (it was created by npx create-expo-app or npx expo prebuild), you can enable the New Architecture by setting the newArchEnabled property to "true" in the Podfile.properties.json file. Otherwise, refer to the "Enable the New Architecture for Apps" section of the React Native New Architecture working group.

故障排除

¥Troubleshooting

Meta 和 Expo 正在努力使新架构成为所有新应用的默认架构，并确保尽可能轻松地迁移现有应用。但是，新架构不仅仅是一个名字 - React Native 的许多内部结构都经过了重新架构和从头开始重建。因此，你在应用中启用新架构时可能会遇到问题。以下是解决这些问题的一些建议。

¥Meta and Expo are working towards 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.

Can I still try the New Architecture even if some of the libraries I use aren't supported?

是的！即使你使用的某些库不受支持，你也可以在应用中尝试新架构。在你的存储库中创建一个新分支并删除任何不兼容的库，直到你的应用运行。这将让你很好地了解在完全迁移到新架构之前哪些库仍需要工作。我们建议在这些库的存储库上创建问题或拉取请求，以帮助它们与新架构兼容。

¥Yes! You can try the New Architecture in your app even if some of the libraries you use aren't supported. 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.

如果你能报告你的体验，我们也会非常高兴，这样我们就可以了解像你这样的开发者的进展情况，并尽可能为你提供帮助。

¥We'd also love it if you could report your experience, so we can learn how developers like you are getting on and help you out where possible.

Known issues in Expo SDK libraries

虽然可能存在我们不知道的不兼容性，但以下是 Expo SDK 中新架构的已知问题：

¥While there are likely incompatibilities we are not aware of, the following are the known issues with the New Architecture in the Expo SDK:

expo-dev-client:我们目前正在调查 iOS 的稳定性问题，因此你可能会在开发版本中遇到崩溃率增加的问题。

¥expo-dev-client: we are currently investigating issues with stability on iOS, so you may encounter an increased crash rate in your development builds.
expo-notifications:本地通知有效，但远程通知尚未完全支持。

¥expo-notifications: local notifications work, but remote notifications not yet fully supported.
expo-task-manager 和 expo-background-fetch:尚不支持。

¥expo-task-manager and expo-background-fetch: not yet supported.
expo-location:尚不支持后台位置。

¥expo-location: background location is not yet supported.

Known issues in React Native

在开发过程中快速重新加载应用可能会导致应用崩溃。修复正在进行中。

¥Reloading the app quickly in development may cause the app to crash. A fix is in progress.

Known issues in third-party libraries

在 React Native 0.74 中，默认情况下启用了各种 Interop Layers，这使得许多库无需任何更改即可工作。但是，它并不完美，一些库需要更新。最有可能需要更新的库是那些附带或依赖第三方原生代码的库。了解有关新架构中的库支持的更多信息。

¥In React Native 0.74, there are various Interop Layers enabled by default which allows many libraries to work without any changes. However, it's 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 目录更完整的库列表及其与新架构的兼容性。以下库在 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 popular among Expo apps and are known to be incompatible:

React Native Firebase：这套库尚不支持新架构。

¥React Native Firebase: this suite of libraries does not yet support the New Architecture.
@react-native-community/masked-view:改用 @react-native-masked-view/masked-view。

¥**@react-native-community/masked-view**: use @react-native-masked-view/masked-view instead.
@react-native-community/clipboard:改用 @react-native-clipboard/clipboard。

¥**@react-native-community/clipboard**: use @react-native-clipboard/clipboard instead.
rn-fetch-blob:改用 react-native-blob-util。

¥rn-fetch-blob: use react-native-blob-util instead.
react-native-fs:改用 expo-file-system 或 react-native-fs 的一个分支。

¥react-native-fs: use expo-file-system or a fork of react-native-fs instead.
react-native-geolocation-service:改用 expo-location。

¥react-native-geolocation-service: use expo-location instead.
react-native-datepicker:改用 react-native-date-picker 或 @react-native-community/datetimepicker。

¥react-native-datepicker: use react-native-date-picker or @react-native-community/datetimepicker instead.
@shopify/flash-list:在某些情况下可能不正确。迁移应用时请务必彻底测试，如果遇到问题，请考虑暂时返回 FlatList。

¥**@shopify/flash-list**: may have not correctly in some cases. Be sure to test it thoroughly when migrating your app, and consider temporarily moving back to FlatList if you encounter issues.

My build failed after enabling the New Architecture

这并不完全令人惊讶！并非所有库都兼容。阅读日志以确定哪个库不兼容。首先要做的是尝试将其更新到最新版本，如果问题仍然存在，请尝试暂时将其从 package.json 和应用代码中删除。重复此操作直到你的应用运行。

¥This isn't entirely surprising! Not all libraries are compatible yet. Read the logs to determine which library is incompatible. The first thing to do is to try updating it to the latest version, and if the issue persists, try temporarily removing it from your package.json and from your application code. Repeat this until your app runs.

一旦你的应用正在运行，你就可以决定是否寻找与新架构兼容的替代库，并将遇到的任何问题报告给库维护者。创建最小可重复示例并将问题报告给库作者（如果适用）或 React Native 团队（如果你认为问题源于 React Native 本身）。

¥Once you have a running app, you can decide whether to look for alternative libraries that are compatible with the New Architecture, and report any issues you encounter to the library maintainers. Create a minimal reproducible example and report the issue to the library author, if applicable, or to the React Native team if you believe the issue originates in React Native itself.