React Native 的新架构

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

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

新架构是我们用来描述 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 团队的博客文章概述了新架构的功能及其构建背后的动机。

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

¥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

运行 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"]
      }
    }
  }
}

See all available options

已启用：如果是 true，则检查将警告 React Native 目录中是否缺少任何包。将其设置为 false 以禁用此行为。在 SDK 52 及以上版本中，默认设置为 true，否则默认为 false。你还可以使用 EXPO_DOCTOR_ENABLE_DIRECTORY_CHECK 环境变量覆盖此设置（0 为 false，1 为 true）。

¥enabled: If true, the check will warn if any packages are missing from React Native Directory. Set this to false to disable this behavior. On SDK 52 and above, this is set to true by default, otherwise it is false by default. You can also override this setting with the EXPO_DOCTOR_ENABLE_DIRECTORY_CHECK environment variable (0 is false, 1 is true).
排除：列出你想要从检查中排除的任何包。支持精确的包名称和正则表达式模式。例如，["exact-package", "/or-a-regex-.*/"]。

¥exclude: List any packages you want to exclude from the check. Supports exact package names and regex patterns. For example, ["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.

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

¥Initialize a new project with the New Architecture

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

¥As of SDK 52, all new projects will be initialized with the New Architecture enabled by default.

Terminal

- npx create-expo-app@latest

在现有项目中启用新架构

¥Enable the New Architecture in an existing project

在目标平台上设置 newArchEnabled：

¥Set newArchEnabled on target platforms:

要在 Android 和 iOS 上启用它，请在应用配置中 expo 对象的根目录下使用 newArchEnabled。你可以通过设置（例如 "android": { "newArchEnabled": true }）有选择地为单个平台启用它。

¥To enable it on both Android and iOS, use the newArchEnabled at the root of the expo object in your app config. You can selectively enable it for a single platform by setting, for example, "android": { "newArchEnabled": true }.

app.json

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

要启用它，你需要在目标平台上安装 expo-build-properties 插件并设置 newArchEnabled。

¥To enable it, you need to install the expo-build-properties plugin and set newArchEnabled on target platforms.

app.json

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

创建新构建：

¥Create a new build:

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

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

¥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 (which is 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.

在现有项目中禁用新架构

¥Disable the New Architecture in an existing project

从 SDK 52 开始，Expo Go 仅支持新架构，因为 Expo Go 中包含的所有 Expo 库和第三方库都支持新架构。请注意 Go 应用不打算用作实际应用的开发环境。

¥Starting SDK 52, Expo Go only supports the New Architecture since all Expo libraries and third-party libraries included in Expo Go support the New Architecture. Note that the Go app is not intended to be used as a development environment for real-world apps.

如果你想选择不使用新架构，无论你使用的是 Expo Go 还是开发版本，请从应用配置中删除 newArchEnabled 属性并创建开发构建。

¥If you want to opt out of using the New Architecture, whether you are using Expo Go or a development build, remove the newArchEnabled property from app config and create a development build.

故障排除

¥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?

即使你使用的某些库不受支持，你也可以在应用中尝试新架构，但这需要暂时删除这些库。在你的存储库中创建一个新分支，并在你的应用运行之前删除任何不兼容的库。这将让你很好地了解在完全迁移到新架构之前哪些库仍需要工作。我们建议在这些库的存储库上创建问题或拉取请求，以帮助它们与新架构兼容。或者，你可以切换到与新架构兼容的其他库。请参阅 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.

Known issues in Expo SDK libraries

截至 SDK 52，以下是 Expo SDK 中新架构的已知问题：

¥As of SDK 52, the following are the known issues with the New Architecture in the Expo SDK:

expo-location:尚不支持后台位置。

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

你可能会在较旧的 SDK 版本中遇到其他问题。我们建议升级到最新的 SDK 版本。

¥You may encounter other issues in older SDK releases. We recommend upgrading to the latest SDK version.

Known issues in React Native

参考标有“类型：React Native GitHub 存储库上的“新架构”。

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

Known issues in third-party 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 目录更完整的库列表及其与新架构的兼容性。以下库在 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:

@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.

My build failed after enabling the New Architecture

这并不完全令人惊讶！并非所有库都兼容，在某些情况下，兼容性是最近才添加的，因此你需要确保将库更新到最新版本。阅读日志以确定哪个库不兼容。此外，运行 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).