5月27日 15:25

Expo SDK 升级怎么做？版本管理流程与避坑要点

Expo SDK 大约每四周发布一个新版本，每个版本绑定特定的 React Native 版本和原生依赖。升级做得好，项目稳定推进；升错了，可能卡在依赖冲突里半天出不来。这篇文章把版本管理的核心流程和踩坑经验讲清楚。

Expo SDK 的版本号规则

Expo SDK 采用语义化版本号（Major.Minor.Patch），但和普通 npm 包不同，SDK 的主版本号是真正意义上的大版本——每个 Major 版本对应一组固定的 React Native 版本、原生编译工具链和支持的最低操作系统版本。

举几个实际例子：

SDK 55 对应 React Native 0.83.1 + React 19.2.0，iOS 最低 15.1
SDK 56 对应更新版本的 React Native，iOS 最低要求跳到 16.4，直接淘汰了 iPhone 6s、iPhone 7 和第一代 iPhone SE

这意味着升级 SDK 不只是改一个版本号，你需要确认项目支持的最低设备不会被新版本排除在外。

查看和管理当前 SDK 版本

最直接的方式是看 package.json：

json
{
  "dependencies": {
    "expo": "~55.0.0"
  }
}

~55.0.0 表示接受 Patch 级别的自动更新，但不会跨 Minor 版本。这个写法是 Expo 推荐的，能保证你拿到安全补丁而不会意外引入不兼容的变更。

用命令行查看当前安装的版本：

bash
npx expo --version

升级 SDK 的完整流程

第一步：建分支，跑诊断

升级之前先创建一个专门的分支，方便出问题时直接回退。然后跑一遍诊断，了解当前项目的健康状况：

bash
npx expo-doctor

这一步特别重要——expo-doctor 会列出所有版本不匹配的依赖、过期的配置和已废弃的 API。升级前解决这些问题，能避免升级后问题叠加。

第二步：安装新版本 SDK

bash
npx expo install expo@latest

这里用 npx expo install 而不是 npm install，是因为 Expo 的安装命令会自动处理版本兼容性，确保安装的包版本和当前 SDK 匹配。手动改 package.json 容易引入版本冲突。

第三步：修复所有依赖

bash
npx expo install --fix

这条命令会把所有 Expo 相关的依赖包升级到和新 SDK 兼容的版本。从 SDK 55 开始，Expo 统一了所有包的版本号——比如 SDK 55 下 expo-camera 的版本是 ^55.0.0，不再各包各版本，管理起来清楚很多。

第四步：重新生成原生代码

如果你使用 Continuous Native Generation（CNG），直接删掉旧的 android 和 ios 目录，让 Expo 重新生成：

bash
npx expo prebuild --clean

如果不用 CNG，有 ios 目录的话需要跑一下 pod install：

bash
npx pod-install

然后分别在两个平台测试：

bash
npx expo run:ios
npx expo run:android

升级中最容易踩的坑

不要跳版本升级

Expo 官方明确建议逐个版本升级。从 SDK 53 直接跳到 55 看似省事，但中间跨了两个 React Native 大版本，一旦出问题你根本分不清是哪个版本引入的。正确做法是 53→54，测试通过后再 54→55。

第三方库兼容性

升级后最常见的问题是第三方库还没适配新 SDK。特别是 SDK 55 强制启用了 New Architecture，很多老库如果不支持新架构就会直接崩溃。升级前先检查你依赖的关键库是否已经声明支持目标 SDK 版本。

app.json 的废弃字段

SDK 55 把通知配置从 app.json 的 notification 字段移到了 expo-notifications 的 config plugin 里。如果你还在用旧的写法，升级后通知功能会失效。另外 newArchEnabled 这个配置项也被移除了——新架构默认开启，不需要手动声明。

expo-av 被拆分

SDK 55 中 expo-av 从 Expo Go 里移除了，需要分别迁移到 expo-video 和 expo-audio。如果你的项目用了音视频播放，这是升级时必须处理的事项。

Expo Go 的版本限制

Expo Go 只支持最新的 SDK 版本。旧版本在 iOS 上尤其严格——受平台限制，只有最新版本的 Expo Go 才能装到真机上。所以如果你的开发工作流依赖 Expo Go，就必须跟着最新 SDK 走。

生产应用建议使用 Development Build，EAS 服务对旧 SDK 版本的向后兼容通常能维持六个月左右，比 Expo Go 宽裕得多。

回退方案

升级后如果遇到解不了的问题，可以回退到之前的版本：

bash
npx expo install expo@54.0.0
npx expo install --fix
npx expo prebuild --clean

回退时同样需要修复依赖和重新生成原生代码，流程和升级一样。所以前面说的建分支很重要——直接切回旧分支比手动回退靠谱得多。

实际项目中的版本管理建议

定期升级，别攒大版本。 每次只升一个版本，升完跑完测试再升下一个。攒了好几个版本再一起升，排查问题的成本会成倍增长。

关注 Changelog。 每个 SDK 版本的发布说明里列出了所有破坏性变更和弃用 API，升级前花十分钟看一遍能省掉后面几小时的调试时间。

优先在开发环境验证。 不要跳过双平台测试，iOS 和 Android 的原生层差异很大，一个平台跑通不代表另一个也没问题。

记录升级日志。 每次升级记录当前版本、目标版本、遇到的问题和解决方案，下次升级时有据可查。

标签：Expo