用途:指导升级 Expo SDK 版本并修复升级过程中的依赖问题,同时提供各版本破坏性变更的迁移参考。
主要能力:
- 提供分步升级流程:npx expo install expo@latest、npx expo install --fix,再用 npx expo-doctor 诊断。
- 缓存清理与重装:npx expo export -p ios --clear,删除 node_modules 与 .expo,watchman watch-del-all。
- 原生变更时执行 npx expo prebuild --clean 重新生成 ios 和 android 目录;裸工作流可清理 CocoaPods、Xcode derived data 与 Gradle 缓存。
- 破坏性变更清单:检查被移除 API、更新移动模块的导入路径、审查需 prebuild 的原生模块、测试相机音频视频与导航。
- 废弃包替换:expo-av 拆分为 expo-audio 与 expo-video,expo-permissions 改为各包权限 API,@expo/vector-icons 对应 expo-symbols,AsyncStorage 对应 expo-sqlite/localStorage/install,expo-app-loading 对应 expo-splash-screen,expo-linear-gradient 对应 experimental_backgroundImage 与 CSS 渐变。迁移时先更新全部代码用法再移除旧包。
- 版本参考:新架构迁移、React 19 变更(useContext 改 use、Context.Provider 改 Context、移除 forwardRef)、React Compiler 配置、原生标签变更、expo-av 到 expo-audio/video 的迁移。
- 测试版:使用 .preview 后缀与 @next 标签,可用 npx expo install expo@next --fix 安装。
使用方式:按升级流程执行命令,结合 npx expo-doctor 与缓存清理排查问题;升级前查阅目标 SDK 版本的发布说明。
限制与注意:prebuild --clean 会重新生成原生目录,运行前需确认项目不是裸工作流应用;SDK 54 及以后需安装 react-native-worklets 以支持 react-native-reanimated;SDK 54+ 可在 app.json 中启用 React Compiler;建议删除 app.json 的 sdkVersion,移除 package.json 中隐式包,精简 babel.config.js 与 metro.config.js;SDK 53 起不再需要 autoprefixer 并使用 postcss.config.mjs;Expo webpack 已废弃,应迁移到 Expo Router 与 Metro web;Expo Go 自 SDK 53 起仅支持新架构。具体版本行为与兼容性以官方发布说明为准。