React Native 的新架构

编辑

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

我们建议使用最新的 Expo 版本，以获得最佳的新架构体验。

新架构是一个用来描述 React Native 内部完全重构的名称。它还用于解决在 Meta 和其他公司多年使用中发现的原始 React Native 架构的局限性。

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

新架构来了

来自 Meta 的 React Native 团队的一篇博客文章，概述了新架构的特性及其构建动机。

为什么迁移到新架构？

新架构是 React Native 的未来 — 然而，对于许多应用程序来说，今天迁移可能没有太多即时好处。您可能想把迁移到新架构视为对您的应用未来的投资，而不是立即改善应用的一种方式。

话虽如此，新的 React 和 React Native 特性仅在新架构中出现。例如，新架构包括对 Suspense 的全面支持，而新的样式功能在传统架构中并未实现。像 @shopify/flash-list 和 react-native-reanimated 这样的库将发布新的主要版本，以充分利用新特性，从而提供比之前更好的性能，并将不再支持传统架构。

传统架构不会永远存在 — 传统架构可能会在 2025 年晚期的发布中被移除。当它被移除时，您将无法在不迁移到新架构的情况下升级 React Native 或 Expo SDK。

Expo 工具和新架构

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

此外，所有使用 Expo 模块 API 编写的模块默认支持新架构！因此，如果您使用此 API 构建了自己的本地模块，则无需额外工作即可与新架构一起使用。

截至 2025 年 4 月，约 75% 的使用 EAS Build 构建的 SDK 52+ 项目采用新架构。

第三方库和新架构

许多最流行的库的兼容性状态在 React Native 目录上进行了跟踪（了解有关第三方库的已知问题）。我们已经将工具集成到 Expo Doctor 中，以与 React Native 目录集成，帮助您验证依赖项，这样您就可以快速了解哪些库没有维护，哪些与新架构不兼容或未经测试。

使用 React Native 目录验证您的依赖项

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

Terminal

- npx expo-doctor@latest

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

package.json

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

查看所有可用选项

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

使用新架构初始化新项目

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

Terminal

- npx create-expo-app@latest

在现有项目中启用新架构

新架构默认在 SDK 53 及更高版本中启用。如果您明确禁用了它，请移除该配置以启用它。

我们建议升级到 SDK 53，以确保您的应用能够利用所有最新的新架构相关修复和改进，无论是库还是 React Native 本身。如果您想先在 SDK 52 上试用，请遵循以下说明。

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

app.json

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

创建新构建：

Terminal

# 运行清理预构建并开始本地构建（如果需要）

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

# 如果您更喜欢，通过 EAS 运行构建

- eas build -p android

Terminal

# 运行清理预构建并开始本地构建（如果需要）

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

# 如果您更喜欢，通过 EAS 运行构建

- eas build -p ios

如果构建成功，您现在可以使用新架构运行您的应用！根据您使用的本地模块，您的应用可能会立即正常工作。

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

我们建议至少升级到 SDK 52，最好是 SDK 53。您可以在 SDK 51 中启用新架构，但您很可能会遇到各种在较新版本中已解决的问题。要启用它，您需要安装 expo-build-properties 插件并在目标平台上设置 newArchEnabled。

您是在一个裸 React Native 应用中启用新架构吗？

如果您使用的是 Expo SDK 53 或更高版本，新架构将默认启用。以下说明适用于旧项目。

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

在现有项目中禁用新架构

: Expo Go 仅支持新架构。

如果您想选择退出使用新架构，请在应用配置中将 newArchEnabled 属性设置为 false 并创建一个开发构建。

app.json

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

您是在一个裸 React Native 应用中禁用新架构吗？

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

故障排除

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

即使我使用的一些库不受支持，我仍然可以尝试新架构吗？

即使我使用的一些库不受支持，您仍然可以尝试在您的应用中使用新架构，但这需要暂时移除那些库。在您的代码库中创建一个新分支，并移除所有不兼容的库，直到您的应用可以正常运行。这将使您对哪些库需要在完全迁移到新架构之前进行改进有良好的了解。我们建议您在这些库的代码库中创建问题或拉取请求，以帮助它们与新架构兼容。或者，您可以切换到与新架构兼容的其他库。请参考 React Native 目录以查找兼容的库。

React Native 中的已知问题

请参考 React Native GitHub 存储库中标记为“类型：新架构”的问题。

Expo 库中的已知问题

在 Expo 库中没有与新架构相关的已知问题。

第三方库中的已知问题

自 React Native 0.74 以来，默认启用了各种互操作层。这使得为旧架构构建的许多库能够在新架构中无须任何更改即可工作。然而，互操作并不完美，某些库需要更新。最可能需要更新的库是那些发货或依赖于第三方本地代码的库。了解新架构中库的支持。

请参考 React Native 目录来获得更完整的库及其与新架构兼容性列表。以下库在 Expo 应用中被发现是流行的，并且已知不兼容：

以下是与 Expo 应用中流行库相关的已知问题。

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 目录中的数据是否一致。

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