如何升级到 Expo SDK 55
如何升级到 Expo SDK 55：分步提示、新架构迁移建议、破坏性变更，以及让升级顺利完成的故障排查。
中文
复制
Expo SDK 55 已发布，支持 React Native 0.83.2 和 React 19.2。与 SDK 54 一样，支持 Android API level 36 以及 Xcode 16.1 及以上版本。最低支持的操作系统同样没有变化：SDK 55 可以为 Android 7+ 和 iOS 15.1 及以上版本构建应用。查看更新日志了解全部内容。下面是一段简短的亮点视频：
每个 SDK 都要经过大量测试和一段 beta 测试期，Expo 团队与社区在此期间协作排查问题，避免这些问题影响其他人快速、顺利地升级。许多 Expo 工程师维护着自己的应用，beta 一发布就会尝试升级。
即便如此，现实中的情况几乎无穷无尽。每个应用都是独特的，都有自己的复杂之处，升级时都需要考虑。因此，我们想重点说明一些可能影响你升级到 SDK 55 的关键变化，以及一些升级到最新 Expo SDK 的通用建议。
升级到 SDK 55 前需要了解的关键事项
React Native 旧架构走到尽头
SDK 54 / React Native 0.81 是最后一批支持旧架构的版本。如果你要采用 SDK 55，就必须同时采用新架构——如果你还没迁移的话。SDK 53 中它已经是默认选项，所以大多数应用已经完成了升级。迁移到新架构的建议见下文。
用 Claude Code 助力 SDK 升级
在 Expo，我们日常工作中就在使用 Claude Code。基于我们的经验，我们发布了一些 skills，用于处理 Expo 应用中的常见任务，放在 expo/skills 仓库中。其中之一就是升级到最新 Expo SDK 版本。除了更新包版本这类基本操作，它还能处理破坏性变更、清理过时配置等等。
在终端的 Claude Code 中运行
/plugin marketplace add expo/skills将 skills marketplace 添加到 Claude，然后运行
/plugin install upgrading-expo安装升级 skill。重启 Claude 后，用自然语言让它升级你的 SDK 即可。如果安装正确，Claude 启动时应该会引用这个 skill：
你也可以通过
bunx skills add expo/skills
``` 把 Expo skills 导入其他 agent。
和往常一样，在单独的分支上干活，合并和部署前先 review 代码。LLM 很强，但 Claude 和 Expo 升级 skill 不可能覆盖所有情况。人类开发者在这个流程里不可或缺。
### 默认项目与 Expo Go 的过渡期
本次发布后的一小段时间内，App Store 和 Play Store 上的 Expo Go 仍会停留在 SDK 54，用 `npx create-expo-app` 创建的默认项目也会继续使用 Expo SDK 54，以保持一致。
Expo Go 是我们快速上手的工具，它的定位是教学，帮你学会在移动端做开发。建议你利用这段过渡期，把项目迁移到 [development build](https://docs.expo.dev/develop/development-builds/expo-go-to-dev-build/)——你要上架应用商店所需的一切，它都能提供。
过渡期内，Android 设备可以直接通过 Expo CLI 安装 SDK 55 版的 Expo Go。iOS 则可以用 [TestFlight External Beta](https://testflight.apple.com/join/GZJxxfUU)，或者用新增的 `eas go` 命令构建一个 SDK 55 的 Expo Go，上传到你自己的 TestFlight 团队。
### expo-av → expo-video / expo-audio
SDK 55 移除了 `expo-av` 包。在更早的 SDK 中，我们已经逐步用改进后的 `expo-audio` 和 `expo-video` 替代了它的功能，所以你应该把代码升级到这两个包。
### 试试 Hermes v1 带来的性能提升
新的 [Hermes v1 编译器](https://blog.swmansion.com/welcoming-the-next-generation-of-hermes-67ab5679e184)能带来可观的性能提升，值得在你的应用里试一试。SDK 55 中它是可选项。注意在这个版本里，某些情况下它会拖慢构建时间，因为它需要从源码构建 React Native，而不能用预编译的二进制文件。启用方法详见 SDK 55 changelog。
## 升级 Expo SDK 的几点建议
我们整理了一份[详细的排错指南，专门针对升级过程中遇到的问题](https://github.com/expo/fyi/blob/main/troubleshooting-sdk-upgrades.md)。里面既讲了升级前要做的准备，也讲了升级中要注意的事项，并按从最省事到最麻烦的顺序列出了一系列建议。整篇指南都值得读一遍，这里先挑几个重点简单说说：
### 先看 changelog！
大多数 SDK 版本都会列出已知的破坏性变更，或者那些需要你针对自己 App 的具体场景调整配置的改动。[changelog](https://expo.dev/changelog/sdk-54)和破坏性变更最好在升级前就看，这样可以在测试之前把配置改好；如果错过了，退而求其次是在升级之后看，尤其是遇到编译错误或崩溃的时候。
### 用 development build 代替 Expo Go
升级最好在时间宽裕的时候做。SDK 发布后，你手机上的 Expo Go 会自动升到最新版，这时你可能会发现 App 在 Expo Go 里跑不起来了，于是觉得必须马上跟着升级，才能继续开发功能。
[Development build](https://docs.expo.dev/develop/development-builds/introduction/)能帮你降降温，让你有时间和空间从容升级，同时不打断正在推进的功能开发。Development build 用起来和 Expo Go 很像，扫个二维码就能在本地调试代码，不用重新构建。但它是你自己的 App，所以 Expo Go 发布新版本时，它不会被一起升级。
如果你还是觉得非用 Expo Go 不可，要知道你并不一定得用 Play 和 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 能还原生产环境 App 的程度相当有限，经常出现「在 Expo Go 里好好的，构建成生产版本就出问题」的情况。Expo Go 能跑你的 JavaScript，但 app.json / app.config.js 里的大部分配置它都用不上，因为那需要改动原生代码。一句话，你的 App 里那些独特、特别的东西，Expo Go 几乎都装不下，development build 可以。用[免费套餐](https://expo.dev/pricing)做几个 development build 绰绰有余，也可以在本地构建 `npx expo run:android` 或 `npx expo run:ios`。
### 关于新架构的建议
Expo SDK 54 是最后一个支持旧架构的 SDK。SDK 55 / React Native 0.83 只支持新架构。所以，如果你还没升级到新架构，现在绝对是时候了！一些主流库的最新版本，比如 `react-native-reanimated` v4 和 `@shopify/flash-list` v4，也只支持新架构。
**不要同时升级 Expo SDK 和迁移到新架构。** 这样会让问题更难定位。相比升级 Expo SDK，迁移到新架构的改动更大，所以出问题大概率跟它有关——但如果你两件事一起做，就很难判断问题出在哪。
我们的建议是先在 SDK 54 上[升级到新架构](https://docs.expo.dev/guides/new-architecture/#enable-the-new-architecture-in-an-existing-project)，然后创建一个 development build。测试一下，遇到问题可以参考我们的[新架构排错指南](https://docs.expo.dev/guides/new-architecture/#troubleshooting)。确认只升级新架构就能正常跑起来之后，再升级到 SDK 55 并重新构建 development build。这样你测试的就只是 SDK 55 升级本身。
### 查看排错指南
我们整理了一个[常见排错指南](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 分钟做一个最小复现，往往也比在真实项目里调试几个小时更有效——真实项目里变量太多，问题更难隔离。
我们也理解，遇到问题时立刻讨论是有价值的，哪怕你还没准备好复现它。其他开发者可能正经历同样的情况，并且已经有答案了。在 [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 55！