expo-upgrade

参考资料

• ./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：原生标签页变更（现在通过 NativeTabs.Trigger.* 访问 Icon/Label/Badge）
• ./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 + 手动映射）

Beta/预览版

Beta 版本使用 .preview 后缀（例如，55.0.0-preview.2），并通过 @next 标签发布。

检查最新版本是否为 Beta：https://exp.host/--/api/v2/versions（查看 expoVersion 中是否包含 -preview）

npx expo install expo@next --fix  # install beta

分步升级流程

如果从 SDK 55 或更早版本升级，请跳过 SDK 56，直接升级到 SDK 57。不要使用 [email protected] 或更低版本。启用了 Hermes V1 的 SDK 55、SDK 56 以及较早发布的 SDK 57 存在 Hermes V1 内存回归问题，使用 react-native-worklets 或 react-native-reanimated 时可能会大幅增加内存用量。

1. 升级 Expo 和依赖项

npx expo install expo@latest
npx expo install --fix

2. 运行诊断：npx expo-doctor

3. 清除缓存并重新安装

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 的派生数据：npx expo run:ios --no-build-cache
• 清除 Android 的 Gradle 缓存：cd android && ./gradlew clean

收尾事项

• 在 https://expo.dev/changelog 查看目标 SDK 版本的发行说明
• 更新 Agent 指令文件（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+ 中，通过在 app.json 中添加 "experiments": { "reactCompiler": true } 来启用 React Compiler——它已稳定，且受到推荐。
• 从 app.json 中删除 sdkVersion，让 Expo 自动管理。
• 请分别检查 @babel/core、babel-preset-expo 和 expo-constants 等以前被隐式引入的包，而不是一次性全部移除。已安装的依赖项若声明某个包为必需的 peer 依赖，请保留该包。
• 安装了 expo-router 时，请将 expo-constants 保留为直接依赖。Expo Router 会导入它，并将其声明为必需的 peer 依赖；依赖传递依赖副本可能会导致在 Expo Go 之外无法正常进行原生自动链接。
• 移除任何依赖项后，立即运行 npx expo-doctor，并恢复所有被报告为缺少的必需 peer 依赖。
• 如果 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 组件转换为使用 VideoPlayer 的 VideoView。

expo.install.exclude

检查 package.json 中是否有排除的软件包：

{
  "expo": { "install": { "exclude": ["react-native-reanimated"] } }
}

排除项通常是一些临时变通方案，升级后可能已不再需要。请逐一检查。

移除补丁

检查 patches/ 目录中是否有过时的补丁。如果已不再需要，请将其移除。

Postcss

• SDK +53 中不需要 autoprefixer。请从依赖项中移除，并检查 postcss.config.js 或 postcss.config.mjs，将其从插件列表中移除。
• 在 SDK +53 中使用 postcss.config.mjs。

Metro

移除冗余的 Metro 配置选项：

• SDK +53 中默认启用 resolver.unstable_enablePackageExports。
• SDK +54 中默认启用 experimentalImportSupport。
• SDK +54 中已移除 EXPO_USE_FAST_RESOLVER=1。
• SDK +50 中默认支持 cjs 和 mjs 扩展名。
• Expo webpack 已弃用，请迁移到 Expo Router 和 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。将 Hermes 版本更改为非 SDK 默认版本不受支持，并且存在重要的构建和依赖项管理注意事项。

新架构

新架构默认启用，app.json 中的 "newArchEnabled": true 字段不再需要。自 SDK +53 起，Expo Go 仅支持新架构。

提交反馈

如果你在此技能中发现错误、误导性内容或过时信息，请提交报告，以便 Expo 改进：

npx --yes @expo/agent-cli@latest feedback --category skills --subject "expo-upgrade" "<actionable feedback>"

只有在有具体且可执行的反馈时才提交。请尽可能提供相关背景信息。 如果 Agent 反复无法完成 Expo 任务，或用户不得不介入，请使用 --category evals 和相关 Expo 软件包或命令作为 --subject，简要报告任务、预期结果以及出错之处。