React Native 的新架构

编辑页面

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

SDK 55 及以后版本完全运行在新架构上。新架构始终处于启用状态，且无法禁用。如果你需要使用旧版架构，请使用 SDK 54 或更早版本。

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

在本指南中，我们将介绍如何在 Expo 项目中使用新架构。

新架构来了

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 月被冻结，这意味着它不会再开发新功能或修复 bug。

新的 React 和 React Native 功能只会面向新架构推出。例如，新架构包括对 Suspense 的完整支持以及新的样式能力，而这些在旧版架构中都没有实现。许多流行库现在也只支持新架构。

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

Expo 工具与新架构

从 SDK 53 开始，Expo SDK 中所有 expo-* 包都支持新架构（包括 bridgeless）。了解更多已知问题。

此外，所有使用 Expo Modules API 编写的模块默认都支持新架构！因此，如果你已经使用该 API 构建了自己的原生模块，那么无需额外工作即可在新架构中使用它们。

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

第三方库与新架构

许多最流行库的兼容性状态都可以在 React Native Directory 上跟踪（了解第三方库中的已知问题）。我们已在 Expo Doctor 中集成了与 React Native Directory 的工具，以帮助你验证依赖项，因此你可以快速了解哪些库无人维护，以及哪些库与新架构不兼容或尚未测试。

使用 React Native Directory 验证依赖项

运行 npx expo-doctor 来检查你的依赖项是否符合 React Native Directory 中的数据。

Terminal

- npx expo-doctor@latest

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

package.json

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

查看所有可用选项

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

使用新架构初始化新项目

从 SDK 52 开始，所有新项目在初始化时默认都会启用新架构。

Terminal

- npx create-expo-app@latest --template default@sdk-55

在现有项目中启用新架构

在 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

# 如果你愿意，可以运行一次干净的 prebuild 并启动本地构建

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

# 如果你更喜欢，可以使用 EAS 运行构建

- eas build -p android

Terminal

# 如果你愿意，可以运行一次干净的 prebuild 并启动本地构建

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

# 如果你更喜欢，可以使用 EAS 运行构建

- eas build -p ios

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

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

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

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

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

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

在现有项目中禁用新架构

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

Expo Go 仅支持新架构。

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

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 新架构工作组中的 "为应用启用新架构" 部分。

故障排除

Meta 和 Expo 正在努力让新架构成为所有新应用的默认选项，并确保尽可能轻松地迁移现有应用。不过，新架构不仅仅是一个名称 — React Native 的许多内部机制都已从头开始重新设计并重建。因此，在你的应用中启用新架构时，可能会遇到一些问题。以下是一些用于排查这些问题的建议。

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

即使你使用的某些库不受支持，你也许仍然可以在应用中尝试新架构，但这需要暂时移除这些库。在你的仓库中创建一个新分支，并移除所有不兼容的库，直到你的应用可以运行。这将帮助你了解在完全迁移到新架构之前，还需要哪些库进行适配。我们建议在这些库的仓库中创建 issue 或 pull request，帮助它们与新架构兼容。或者，你也可以切换到其他与新架构兼容的库。请参阅 React Native Directory 查找兼容的库。

React Native 中的已知问题

请参阅 React Native GitHub 仓库中带有“Type: New Architecture”标签的问题。

Expo 库中的已知问题

Expo 库中没有针对新架构的已知问题。

第三方库中的已知问题

自 React Native 0.74 起，默认启用了多种互操作层。这使得许多为旧架构构建的库无需任何更改即可在新架构上运行。不过，这种互操作并不完美，因此有些库仍需要更新。最可能需要更新的库是那些包含或依赖第三方原生代码的库。了解有关新架构中库支持的更多信息。

请参阅 React Native Directory 以获取更完整的库列表及其与新架构的兼容性。以下库在 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 Directory 中的数据检查你的依赖项。

当你使用某个库的最新版本但它仍不兼容时，请将你遇到的任何问题报告到相应的 GitHub 仓库。创建一个最小可复现示例，并将问题报告给该库的作者。如果你认为问题出在 React Native 本身而不是某个库，请向 React Native 团队报告（同样需要提供最小可复现示例）。