如何升级到 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。本地构建和 EAS Build 都默认开启，无需任何配置。要关掉的话，本地构建把环境变量 EXPO_USE_PRECOMPILED_MODULES 设为 0，EAS Build 则同样把它设为 EAS 环境变量。

Android 这边，expo-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”。

Expo Go 是我们用来快速上手的工具，它的定位是教学，帮你学会在移动端做开发。建议你利用这段过渡期把项目迁移到 development build，它能提供你发布到应用商店所需的一切。

Android 设备可以直接通过 Expo CLI 安装 SDK 56 的 Expo Go。iOS 则可以用 TestFlight External Beta，或者用 eas go 命令自己构建一个 SDK 56 的 Expo Go，上传到自己的 TestFlight 团队。

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

SDK 55 里我们为 expo-updates 和 EAS Update 引入了需要手动开启的 Hermes 字节码差分：客户端不再每次更新都下载完整 bundle，而是下载针对已安装字节码的二进制补丁。

SDK 56 中默认开启 diffing。如需关闭，在 app.json 的 updates 块中设置 "enableBsdiffPatchSupport": false。详见 expo-updates API 参考。

内联 Expo 模块

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

Expo SDK 升级建议

我们整理了升级过程中遇到问题的详细排查建议，涵盖升级前和升级中的注意事项，并附有一份建议清单，按最快、最容易尝试的顺序排列。我们建议通读整篇指南，这里先简要强调几个要点：

用升级 skill！

好用得值得说两遍：把 expo/skills 库添加到你的 LLM 中，让它替你完成升级。

用 Expo MCP 排查问题

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

查看 changelog

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

用开发构建代替 Expo Go

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

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

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

不过，迁移到 development build 还有一个理由：Expo Go 复现生产应用的能力相当有限，于是常出现「在 Expo Go 里没问题，构建生产应用后就出问题」的情况。Expo Go 能跑你的 JavaScript，但 app.json / app.config.js 里的大部分配置它都用不上，因为那需要改动原生代码。简而言之，你的应用里那些独特、特别的东西，Expo Go 几乎都装不下。Development build 可以。Free 套餐的额度足够做几个 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 上升级到新架构，然后再创建开发构建。测试一下，如果遇到问题，可以参考我们的新架构故障排查指南。确认仅升级到新架构就能正常运作后，再升级到 SDK 56 并创建新的开发构建。这样，你就是在单独测试 SDK 56 的升级。

查看故障排查指南

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

需要帮助就联系我们！

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

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

我们也理解，即使还没准备好复现，当下就讨论问题也有价值。其他开发者可能遇到同样的情况，并且已经有答案。在 Discord、Reddit、Bluesky 等地方讨论问题，可以形成一种协作式的虚拟小黄鸭调试——在交流的过程中一起找到答案。

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

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