参考资料
- ./references/react-19.md -- SDK +54: React 19 变更（useContext → use, Context.Provider → Context, forwardRef 移除）
- ./references/new-architecture.md -- SDK +53: 新架构迁移指南
- ./references/react-compiler.md -- SDK +54: React Compiler 设置和迁移指南
- ./references/native-tabs.md -- SDK +55: 原生标签变更（Icon/Label/Badge 现在通过 NativeTabs.Trigger.* 访问）
- ./references/expo-av-to-audio.md -- SDK +55: 将音频播放和录制从 expo-av 迁移到 expo-audio
- ./references/expo-av-to-video.md -- SDK +55: 将视频播放从 expo-av 迁移到 expo-video
- ./references/react-navigation-to-expo-router.md -- SDK +56: 将
@react-navigation/*导入迁移到expo-router入口点（codemod + 手动映射）
测试版/预览版
测试版使用 .preview 后缀（例如，55.0.0-preview.2），以 @next 标签发布。
检查最新版本是否为测试版：https://exp.host/--/api/v2/versions （查找 expoVersion 中的 -preview）
npx expo install expo@next --fix # 安装测试版
逐步升级流程
如果从 SDK 55 或更早版本升级，请跳过 SDK 56 直接升级到 SDK 57。不要使用
[email protected]或更低版本。SDK 55（启用了 Hermes V1）、SDK 56 以及早期 SDK 57 版本包含一个 Hermes V1 内存回归问题，在使用react-native-worklets或react-native-reanimated时可能会大幅增加内存使用量。
- 升级 Expo 和依赖
npx expo install expo@latest
npx expo install --fix
-
运行诊断：
npx expo-doctor -
清除缓存并重新安装
npx expo export -p ios --clear
rm -rf node_modules .expo
watchman watch-del-all
重大变更检查清单
- 检查版本说明中已移除的 API
- 更新已移动模块的导入路径
- 审查需要预构建的原生模块更改
- 测试所有相机、音频和视频功能
- 验证导航是否仍能正常工作
为原生更改预构建
首先检查项目中是否存在 ios/ 和 android/ 目录。 如果这两个目录都不存在，则项目使用持续原生生成 (CNG) 模式，原生项目会在构建时重新生成——请跳过本节以及“清除裸工作流缓存”部分。
如果升级需要原生更改：
npx expo prebuild --clean
这将重新生成 ios 和 android 目录。在运行此命令之前，请确保项目不是裸工作流应用。
清除裸工作流缓存
仅当项目中存在 ios/ 和/或 android/ 目录时，才执行以下步骤：
- 清除 iOS 的 CocoaPods 缓存：
cd ios && pod install --repo-update - 清除 Xcode 的 Derived Data：
npx expo run:ios --no-build-cache - 清除 Android 的 Gradle 缓存：
cd android && ./gradlew clean
维护工作
- 在 https://expo.dev/changelog 查看目标 SDK 版本的发布说明
- 更新代理指令文件 (
AGENTS.md) 中的版本化文档链接。默认模板链接到https://docs.expo.dev/versions/v<version>/。搜索docs.expo.dev/versions/并将每个链接更新到新的 SDK 版本。 - 如果使用 Expo SDK 54 或更高版本，请确保已安装 react-native-worklets——这是 react-native-reanimated 工作所必需的。
- 在 SDK 54+ 中启用 React 编译器：在 app.json 中添加
"experiments": { "reactCompiler": true }——它稳定且推荐使用 - 从
app.json中删除 sdkVersion，让 Expo 自动管理它 - 审查以前隐含的包，例如
@babel/core、babel-preset-expo和expo-constants，应逐个处理，而不是整体删除。保留任何已安装依赖将其声明为必需对等依赖的包。 - 只要安装了
expo-router，就应保留expo-constants作为直接依赖。Expo Router 会导入它并将其声明为必需对等依赖；依赖传递副本可能会在 Expo Go 之外破坏原生自动链接。 - 移除任何依赖后，立即运行
npx expo-doctor，并恢复它报告为缺失必需对等依赖的任何内容。 - 如果 babel.config.js 仅包含 'babel-preset-expo'，则删除该文件
- 如果 metro.config.js 仅包含 expo 默认值，则删除该文件
已弃用的包
| 旧包 | 替代包 |
|---|---|
expo-av | expo-audio 和 expo-video |
expo-permissions | 单个包的权限 API |
@expo/vector-icons | expo-symbols (用于 SF Symbols) |
AsyncStorage | expo-sqlite/localStorage/install |
expo-app-loading | expo-splash-screen |
| expo-linear-gradient | experimental_backgroundImage + View 中的 CSS 渐变 |
迁移已弃用的包时，请先更新所有代码用法，然后再移除旧包。对于 expo-av，请查阅迁移参考资料，将 Audio.Sound 转换为 useAudioPlayer，Audio.Recording 转换为 useAudioRecorder，Video 组件转换为 VideoView（配合 useVideoPlayer）。
expo.install.exclude
检查 package.json 是否有排除的包：
{
"expo": { "install": { "exclude": ["react-native-reanimated"] } }
}
排除项通常是升级后可能不再需要的变通方法。请逐一审查每个排除项。
移除补丁
检查 patches/ 目录中是否有任何过时的补丁。如果不再需要，请将其移除。
Postcss
autoprefixer在 SDK +53 中不再需要。将其从依赖中移除，并检查postcss.config.js或postcss.config.mjs，将其从插件列表中删除。- 在 SDK +53 中使用
postcss.config.mjs。
Metro
移除冗余的 metro 配置选项：
- resolver.unstable_enablePackageExports 在 SDK +53 中默认启用。
experimentalImportSupport在 SDK +54 中默认启用。EXPO_USE_FAST_RESOLVER=1在 SDK +54 中被移除。- cjs 和 mjs 扩展名在 SDK +50 中默认受支持。
- Expo webpack 已弃用，请迁移到 Expo Router and Metro web。
Hermes 引擎 v1
Hermes V1 是 SDK 56 及更高版本的默认引擎。启用了 Hermes V1 的 SDK 55 应用、所有 SDK 56 应用以及 [email protected] 之前的 SDK 57 应用，在导入 react-native-worklets 或 react-native-reanimated 时可能会遇到内存回归问题。请直接升级到 SDK 57 和 [email protected] 或更高版本。不要推荐使用 Worklets Bundle Mode 作为生产环境的变通方案；它不受支持且是实验性的，可能无法按预期工作。
不要引导用户选择加入或退出 Hermes V1。更改 SDK 默认的 Hermes 版本不受支持，并且存在重大的构建和依赖管理注意事项。
新架构
新架构默认启用，app.json 中的 "newArchEnabled": true 字段不再需要，因为它已经是默认值。自 SDK +53 起，Expo Go 仅支持新架构。
提交反馈
如果您在此技能中遇到错误、误导性或过时的信息，请报告以便 Expo 改进：
npx --yes submit-expo-feedback@latest --category skills --subject "expo-upgrade" "<可操作的反馈>"
仅当您有具体且可操作的内容需要报告时才提交。请尽可能包含相关的上下文。 如果 AI 代理反复失败，或者用户必须接手 Expo 任务，请加载 expo-skill-feedback 技能并遵循其评估候选流程，而不是重复使用上述命令。