upgrading-expo

适用场景

当你需要 Expo SDK 版本升级指南并解决依赖问题时，使用此技能。

参考资料

• ./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

升级边界

先提交项目和 lockfile，或进行备份。每次只升级一个 SDK，并明确选择目标版本；这些参考资料中的 SDK 标签仅供历史参考，应用 API 前请查看目标版本的发布说明和已安装的类型定义。如果原生项目重新生成时丢失了更改，请从检查点恢复。

分步升级流程

1. 升级 Expo 和依赖项

# Replace TARGET with the next intended SDK version, not a floating latest
npx expo install expo@TARGET
npx expo install --fix

2. 运行诊断：npx expo-doctor

3. 仅在诊断结果表明缓存过期时，才从已验证的项目根目录运行；然后使用项目的包管理器重新安装

npx expo export -p ios --clear
npx expo start --clear
# Remove project-local caches only if needed; avoid global Watchman reset.

破坏性变更检查清单

• 查看发布说明，检查已移除的 API
• 更新已迁移模块的导入路径
• 检查需要预构建的原生模块变更
• 测试所有相机、音频和视频功能
• 确认导航仍能正常工作

原生变更的预构建

首先确定原生项目是自动生成还是手动维护；仅凭目录是否存在无法判断。 如果两个目录都不存在，项目使用 Continuous Native Generation（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

收尾工作

• 查看目标 SDK 版本的发布说明：https://expo.dev/changelog
• 如果使用 Expo SDK 54 或更高版本，请确保已安装 react-native-worklets——这是 react-native-reanimated 正常工作的必要条件。
• 在 SDK 54+ 中，通过在 app.json 中添加 "experiments": { "reactCompiler": true } 启用 React Compiler——它已稳定，且推荐使用
• 从 app.json 中删除 sdkVersion，让 Expo 自动管理它
• 只有在检查直接导入、配置用法和目标 SDK 要求后，才移除依赖项；项目可能会直接使用 expo-constants。
• 如果 babel.config.js 仅包含 'babel-preset-expo'，请删除该文件
• 如果 metro.config.js 仅包含 Expo 默认配置，请删除该文件

已弃用的包

旧包	替代方案
expo-av	expo-audio 和 expo-video
expo-permissions	各个包独立的权限 API
@expo/vector-icons	除非有意重新设计图标以适配受支持的平台，否则请保留；SF Symbols 不能直接替代
AsyncStorage	未经明确的数据持久化/API 迁移，不要替换
expo-app-loading	expo-splash-screen
expo-linear-gradient	选择渐变替代方案前，先评估平台支持情况

迁移已弃用的包时，请先更新所有代码用法，再移除旧包。对于 expo-av，请参阅迁移指南，将 Audio.Sound 改为使用 useAudioPlayer，将 Audio.Recording 改为使用 useAudioRecorder，并将 Video 组件改为使用 useVideoPlayer 的 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

从 SDK 55 起，用户可以选择启用 Hermes 引擎 v1，以提升运行时性能。这需要在 expo-build-properties 配置插件中设置 useHermesV1: true，并且可能需要特定版本的 hermes-compiler npm 包。Hermes v1 将在未来某个 SDK 版本中成为默认选项。

新架构

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

限制

• 仅当任务明确符合其上游产品或 API 的适用范围时，才使用此技能。
• 修改前，请根据当前官方文档核实命令、API 行为、定价、配额、凭据和部署影响。
• 不要将生成的示例视为环境专属测试、安全审查，或针对破坏性操作或高成本操作征求用户批准的替代品。