如何升级到 Expo SDK 56

Expo SDK 56 已发布，支持 React Native 0.85 和 React 19.2。支持 Android API level 36 以及 Xcode 26.4 及以上版本。最低支持的操作系统同样保持不变：SDK 56 可以为 Android 7+ 和 iOS 16.4 及以上版本构建应用。查看更新日志以全面了解所有更新内容。下面是一段简短的亮点视频：

每个 SDK 都要经过大量测试和一段 beta 测试期，Expo 团队和社区在此期间共同排查问题，避免这些问题妨碍其他人快速、顺利地升级。许多 Expo 工程师维护着自己的应用，beta 一发布就会尝试升级。

但现实中的可能性几乎无穷无尽。每个应用都是独特的，各有各的复杂之处，升级时都需要考虑。因此，我们想重点说明几个可能影响你升级到 SDK 56 的关键变化，以及一些升级到最新 Expo SDK 时长期适用的建议。

升级到 SDK 56 前需要了解的关键事项

用 Claude Code 助力 SDK 升级

在 Expo，我们日常工作中就在使用 Claude Code。基于我们的经验，我们发布了一些 skills，用于处理 Expo 应用中的常见任务，放在 expo/skills 库中。其中之一就是升级到最新 Expo SDK 版本。除了更新包版本这类基本操作，它还能处理破坏性变更、清理过时配置等。

在终端的 Claude Code 中运行

/plugin marketplace add expo/skills

把 skills marketplace 添加到 Claude，然后运行

/plugin install expo

重启 Claude 后，你可以用自然语言让它升级你的 SDK。如果安装正确，你应该会看到 Claude 在开始工作时引用这个 skill：

你也可以通过

bunx skills add expo/skills
``` 把 Expo skills 导入其他 agent。

和往常一样，在单独的分支上干活，合并和部署前先 review 代码。LLM 很强，但 Claude 和 Expo upgrade skill 不可能覆盖所有情况。人类开发者在这套流程里仍然不可或缺。

### 更快的原生构建

为了加快 iOS 构建，SDK 56 为 iOS 上最复杂的那几个 Expo 模块提供了[预编译 XCFramework](https://docs.expo.dev/guides/prebuilt-expo-modules/)。本地构建和 EAS Build 都默认开启，无需任何配置。要关掉的话，本地构建把环境变量 `EXPO_USE_PRECOMPILED_MODULES` 设为 `0`，EAS Build 则同样把它设为 [EAS 环境变量](https://docs.expo.dev/eas/environment-variables/manage/)。

Android 这边，[`expo-build-properties`](https://docs.expo.dev/versions/v56.0.0/sdk/build-properties/) 新增了一个需要手动开启的 `android.usePrecompiledHeaders` 选项，会对每个自动链接的原生模块的 C++ codegen 输出应用 CMake 预编译头，大幅缩短 Android 上的 CMake 编译时间。

### Expo Go 更新

SDK 56 的 Expo Go 没有上架 Apple App Store 和 Google Play Store。什么时候上架也没有时间表，有消息我们会更新 SDK 56 的 changelog。更多信息可以参考“[Expo Go and the App Store in May 2026](https://expo.dev/changelog/expo-go-and-app-store-may-2026)”。

Expo Go 是我们用来快速上手的工具，它的定位是教学，帮你学会在移动端做开发。建议你利用这段过渡期把项目迁移到 [development build](https://docs.expo.dev/develop/development-builds/expo-go-to-dev-build/)，它能提供你发布到应用商店所需的一切。

Android 设备可以直接通过 Expo CLI 安装 SDK 56 的 Expo Go。iOS 则可以用 [TestFlight External Beta](https://testflight.apple.com/join/GZJxxfUU)，或者用 `eas go` 命令自己构建一个 SDK 56 的 Expo Go，上传到自己的 TestFlight 团队。

### 更新用的 Hermes 字节码差分默认开启

SDK 55 里我们为 `expo-updates` 和 [EAS Update](https://expo.dev/services#update) [引入了需要手动开启的 Hermes 字节码差分](https://expo.dev/changelog/sdk-55#hermes-bytecode-diffing-for-eas-update-and-expo-updates)：客户端不再每次更新都下载完整 bundle，而是下载针对已安装字节码的二进制补丁。

SDK 56 中默认开启 diffing。如需关闭，在 **app.json** 的 `updates` 块中设置 `"enableBsdiffPatchSupport": false`。[详见](https://docs.expo.dev/versions/v56.0.0/sdk/updates/) [`expo-updates`](https://docs.expo.dev/versions/v56.0.0/sdk/updates/) [API 参考](https://docs.expo.dev/versions/v56.0.0/sdk/updates/)。

### 内联 Expo 模块

现在可以直接在项目结构中定义 Expo 模块，与 JavaScript、TypeScript 代码放在一起。我们称之为内联模块，它让原生代码的试验变得前所未有的简单。内联模块属于项目结构的一部分，因此你可以在 Android Studio、Xcode 或任何其他 IDE 中开发它们。更多信息请参阅内联模块[参考文档](https://docs.expo.dev/modules/inline-modules-reference/)和[教程](https://docs.expo.dev/modules/inline-modules-tutorial/)。

## Expo SDK 升级建议

我们整理了[升级过程中遇到问题的详细排查建议](https://github.com/expo/fyi/blob/main/troubleshooting-sdk-upgrades.md)，涵盖升级前和升级中的注意事项，并附有一份建议清单，按最快、最容易尝试的顺序排列。我们建议通读整篇指南，这里先简要强调几个要点：

### 用升级 skill！

好用得值得说两遍：把 [expo/skills 库](https://docs.expo.dev/skills/)添加到你的 LLM 中，让它替你完成升级。

### 用 Expo MCP 排查问题

[Expo MCP](https://docs.expo.dev/eas/ai/mcp) 现在提供了更多工具，可配合 Claude Code、Codex、Cursor 等排查升级问题。如果某个 EAS 构建失败，用 `build_logs` 工具拉取构建日志，交给 AI 分析。如果安装了 `expo-mcp` 包，可以用 `collect_app_logs` 工具从模拟器/仿真器拉取原生 logcat / macOS 控制台日志。

### 查看 changelog

大多数 SDK 版本都会列出已知的破坏性变更，或那些可能需要针对你 app 的特定场景调整配置的显著变更。读 [changelog](https://expo.dev/changelog/sdk-56) 和破坏性变更的最佳时机是升级之前，这样你可以在测试前完成调整；次佳时机是升级之后，尤其是在遇到编译错误或崩溃时。

### 用开发构建代替 Expo Go

升级最好选在你手头不紧、不用赶着完成的时候做。SDK 发布后，你手机上的 Expo Go 会自动升到最新版，这时你可能会发现应用在 Expo Go 里跑不起来了，于是觉得必须马上升级，才能继续开发功能。

[Development build](https://docs.expo.dev/develop/development-builds/introduction/) 能帮你降降温，让你有时间、有余裕地做升级，同时不打断正在推进的功能开发。Development build 的用法和 Expo Go 很像，扫个二维码就能在本地改代码，不用重新构建。但它是你自己的应用，所以 Expo Go 发新版本时，它不会被一起升级。

如果你还是觉得非用 Expo Go 不可，要知道你未必非得用 Play Store 和 App Store 上的最新版。你可以去 [https://expo.dev/go](https://expo.dev/go) 下载旧版本，在 Android 设备和 iOS 模拟器上使用。遗憾的是，受 App Store 限制，iOS 真机上用不了。

不过，[迁移到 development build 还有一个理由](https://expo.dev/blog/expo-go-vs-development-builds)：Expo Go 复现生产应用的能力相当有限，于是常出现「在 Expo Go 里没问题，构建生产应用后就出问题」的情况。Expo Go 能跑你的 JavaScript，但 app.json / app.config.js 里的大部分配置它都用不上，因为那需要改动原生代码。简而言之，你的应用里那些独特、特别的东西，Expo Go 几乎都装不下。Development build 可以。[Free 套餐](https://expo.dev/pricing)的额度足够做几个 development build，你也可以在本地构建 `npx expo run:android` 或 `npx expo run:ios`。

### 关于 New Architecture 的建议

Expo SDK 54 是最后一个支持 Old Architecture 的 SDK。SDK 55+ / React Native 0.83+ 只支持 New Architecture。所以，如果你还没升级到 New Architecture，现在绝对是时候了！不少主流包的最新版本，比如 `react-native-reanimated` v4 和 `@shopify/flash-list` v4，都只支持 New Architecture。

**不要同时升级 Expo SDK 和迁移到 New Architecture。** 这样很难把问题单独隔出来。相比升级 Expo SDK，迁移到 New Architecture 是更大的改动，所以出问题多半和它有关——但如果你两件事一起做，就很难判断了。

我们建议先在 SDK 54 上[升级到新架构](https://docs.expo.dev/guides/new-architecture/#enable-the-new-architecture-in-an-existing-project)，然后再创建开发构建。测试一下，如果遇到问题，可以参考我们的[新架构故障排查指南](https://docs.expo.dev/guides/new-architecture/#troubleshooting)。确认仅升级到新架构就能正常运作后，再升级到 SDK 56 并创建新的开发构建。这样，你就是在单独测试 SDK 56 的升级。

### 查看故障排查指南

我们有一个[最热门故障排查指南](https://docs.expo.dev/troubleshooting/overview/)的汇总页面，你可以根据自己的问题浏览。如果问题是构建时报错，需要采取的步骤与崩溃或性能问题不同。即使你没能完全找到根本原因，在进一步排查或向他人求助时，[使用 ADB Logcat 或 macOS 控制台之类的工具](https://docs.expo.dev/debugging/runtime-issues/#production-app-is-crashing)找到操作系统报告的崩溃原生错误也会非常有帮助。

### 需要帮助就联系我们！

感谢你的 bug 报告和反馈！提出问题的最佳方式永远是提交一个带有**最小复现**的 GitHub issue，附上一个基于默认项目模板（用 `npx create-expo-app` 创建）的 GitHub 仓库链接，再加上刚好足以复现问题的代码。

最小复现能确保我们的团队看到你所看到的情况，也让我们能测试修复方案对你是否有效。即使这看起来工作量不小，花 15 到 30 分钟尝试做一个最小复现，往往也比在实际应用上花几个小时调试更有效——实际应用里变量太多，问题更难隔离。像 Claude 这样的 AI 工具甚至能帮你做最小复现。

我们也理解，即使还没准备好复现，当下就讨论问题也有价值。其他开发者可能遇到同样的情况，并且已经有答案。在 [Discord](https://discord.com/invite/expo)、[Reddit](https://www.reddit.com/r/expo/)、[Bluesky](https://bsky.app/profile/expo.dev) 等地方讨论问题，可以形成一种[协作式的虚拟小黄鸭调试](https://en.wikipedia.org/wiki/Rubber_duck_debugging)——在交流的过程中一起找到答案。

我们鼓励你发截图或视频来说明遇到的问题，或者至少描述清楚你具体看到了什么现象、影响了哪些平台等，这样我们才能知道哪里出了问题，也方便社区一起想办法定位并解决。如果你对升级过程有详细的反馈，又不太适合塞进单个问题的最小复现里，我们也非常欢迎。除了社交论坛，我们的[支持页面](https://expo.dev/support)收到的消息也一直有人查看。

祝你升级顺利，希望你喜欢 SDK 56！