Expo 项目升级到 SDK 55 启用 React Native New Architecture 需要做什么？

如果你要把一个现有的 Expo 项目从 SDK 54 或更早版本升级到 SDK 55，就绕不开一件事：从 SDK 55 起，React Native New Architecture（新架构）始终启用且无法关闭。SDK 55 使用 React Native 0.83，而 React Native 0.82 已经移除了禁用新架构的选项。也就是说，"升级到 SDK 55"和"启用新架构"在 SDK 55 上是同一件事，本文给出这条升级路径的完整操作步骤：更新依赖、处理 newArchEnabled 配置、刷新原生工程、构建验证，以及遇到不兼容第三方库时的排查方式。

升级前先确认前提

根据文档 New Architecture 的说明，升级前需要了解这些事实：

• SDK 55 及以后版本完全运行在新架构上，新架构始终启用，无法禁用。如果你还需要使用旧架构（legacy architecture），只能停留在 SDK 54 或更早版本——SDK 54 是最后一个可以禁用新架构的 SDK 版本。
• SDK 55 使用 React Native 0.83。旧架构在 2025 年 6 月已被冻结，不再接收新功能或修复。
• 如果你之前一直用 Expo Go 跑应用，不需要额外处理：文档明确说明 Expo Go 只支持新架构。
• 项目里所有 expo-* 包自 SDK 53 起就支持新架构（包括 bridgeless）。如果你用 Expo Modules API 自己写过原生模块，它们默认支持新架构，不需要额外改造。

清理 app config 中的 newArchEnabled 设置

如果你之前在 app config（app.json 或 app.config.js）里设置过 newArchEnabled，现在需要把它删掉：

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

文档说明：在 SDK 55 及以后版本中，如果你在 app config 里设置的是 newArchEnabled: false，该设置会被直接忽略；而 newArchEnabled: true 这类显式开启的配置也没有存在意义。为避免混淆，应把这个字段从配置中移除，而不是把它改成 true。

升级 Expo SDK 与依赖

完整的升级流程参考 Upgrade Expo SDK。文档建议逐个版本增量升级（例如先升到 SDK 54 再到 SDK 55），这样出问题时更容易定位是哪一步引入的。以下是目标版本为 SDK 55 的操作：

第 1 步：安装 SDK 55 的 expo 包

npm install expo@^55.0.0

文档中以 expo@^57.0.0 为例，并要求你把版本范围替换为你要升级的目标 SDK 版本；目标 SDK 55 对应 expo@^55.0.0。如果你用其他包管理器，对应的命令是 yarn add expo@^55.0.0、pnpm add expo@^55.0.0 或 bun install expo@^55.0.0。

第 2 步：升级所有依赖并检查项目

npx expo install --fix
npx expo-doctor

npx expo install --fix 会把项目里与 expo 包配套的所有依赖升级到与当前 SDK 版本匹配的版本；随后 npx expo-doctor 用来检查常见问题。

校验第三方库的新架构兼容性

新架构升级中最常见的坑来自第三方库。文档指出：自 React Native 0.74 起启用的 Interop Layers 能让许多旧架构库在新架构上直接工作，但互操作并不完美，携带或依赖第三方原生代码的库最可能需要更新。

Expo Doctor 内置了对 React Native Directory 数据源的校验，可以直接用它判断依赖里哪些库未维护、哪些不兼容或未测试新架构：

npx expo-doctor@latest

如果个别包在 React Native Directory 中没有记录、你确认可以排除，可以在 package.json 里配置 expo.doctor.reactNativeDirectoryCheck：

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

文档列出的可用选项：

• enabled：为 true 时，如果有任何包不在 React Native Directory 中会给出警告；SDK 52 及以后默认为 true，否则默认为 false。也可用环境变量 EXPO_DOCTOR_ENABLE_DIRECTORY_CHECK（0 为 false，1 为 true）覆盖。
• exclude：要从检查中排除的包列表，支持精确包名和正则表达式，例如 ["exact-package", "/or-a-regex-.*/"]。
• listUnknownPackages：默认为 true 时会警告不在 React Native Directory 中的包，设为 false 可关闭该行为。

更新原生工程

升级 SDK 后，本地已有的原生工程文件（android、ios 目录）需要处理，分两种情况：

• 使用 Continuous Native Generation（默认推荐方式）：删除本地的 android 和 ios 目录（如果它们是为旧 SDK 版本生成的）。它们会在下次构建时重新生成，触发方式是 npx expo run:ios、npx expo prebuild 或 EAS Build。
• 不使用 Continuous Native Generation：如果有 ios 目录，运行 npx pod-install；并对照 Native project upgrade helper 应用相关改动。文档同时建议考虑 adopting prebuild，让后续升级更省事。

阅读 SDK 55 的 release notes 并完成构建验证

升级流程的最后一步是阅读目标 SDK 的 release notes：其中包含破坏性变更、弃用项和该版本特有的说明，特别注意页面底部的 "Upgrading your app" 部分。

然后创建一次新构建来验证。本地构建可以用：

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

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

也可以用 EAS Build 替代本地构建：

eas build -p android
# 或
eas build -p ios

构建成功即表示应用已运行在新架构上（文档对 SDK 55 之前的版本给出的验证口径是 "If the build succeeds, you will now be running your app with the New Architecture!"）。构建通过后还要在真机/模拟器上实际点一遍应用做功能测试——文档提醒，多数稍复杂的应用在升级后大概率会遇到一些问题（例如某些原生视图尚未实现新架构版本），这些问题大多可以通过配置或代码修改解决。

构建失败或依赖不兼容时的排查

按 New Architecture 的 Troubleshooting 部分，处理顺序如下：

1. 构建失败：不兼容的库是常见原因。先读构建日志确定是哪个库不兼容，然后把它更新到最新版本；同时再跑一次 npx expo-doctor@latest 对照 React Native Directory 数据检查依赖。
2. 库已是最新版仍不兼容：到该库的仓库提交 issue，并附一个最小可复现示例；如果你判断问题出在 React Native 本身而非库，则报告给 React Native 团队。
3. 有些库暂时不支持、但想先跑起来：文档建议在新分支上临时移除这些不兼容的库，让应用先运行，借此摸清哪些库在新架构迁移完成前还需要处理；也可以切换到兼容新架构的替代库。

文档列出的、在 Expo 应用中流行且已知与新架构存在问题的第三方库（迁移时可以直接对照处理）：

库	文档给出的处理方式
react-native-maps	1.20.x（SDK 53 默认）通过 interop layer 支持新架构，大多数功能可用；1.21.0 是新架构优先的版本，仍在稳定中。如果应用可以强制最低 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 的 fork
react-native-geolocation-service	改用 expo-location
react-native-datepicker	改用 react-native-date-picker 或 @react-native-community/datetimepicker

边界说明

• 本文路径适用于从 SDK 54 或更早版本升级到 SDK 55 的 Expo 项目。如果项目本身就是原生 React Native 项目（非 Expo 管理），SDK 52 及更早的旧式做法（在 gradle.properties 设 newArchEnabled=true、在 Podfile.properties.json 设 newArchEnabled）不再适用于 SDK 55——该版本没有可设置的开关。
• 新架构在 SDK 55 上没有回退选项：如果某个依赖短期无法兼容，文档给出的出路是升级到兼容的新架构替代库，或暂缓升级、继续使用 SDK 54（SDK 54 及更早版本可通过 newArchEnabled: false 关闭新架构并配合 development build 使用）。

相关文档：New Architecture、Upgrade Expo SDK、Development builds。