Upgrading expo

参考资料

• ./references/new-architecture.md — SDK +53：新架构迁移指南
• ./references/react-19.md — SDK +54：React 19 变更（useContext → use， Context.Provider → Context， forwardRef 移除）
• ./references/react-compiler.md — SDK +54：React 编译器设置与迁移指南
• ./references/native-tabs.md — SDK +55：原生标签页变更（图标/标签/徽章现在通过 NativeTabs.Trigger.* 访问）
• ./references/expo-av-to-audio.md — 从 expo-av 迁移音频播放和录制到 expo-audio
• ./references/expo-av-to-video.md — 从 expo-av 迁移视频播放到 expo-video

测试版/预览版

测试版使用 .preview 后缀（例如 55.0.0-preview.2），以 @next 标签发布。

检查最新版本是否为测试版：https://exp.host/–/api/v2/versions（在 expoVersion 中查找 -preview）

npx expo install expo@next --fix  # 安装测试版

逐步升级流程

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/ 目录。 如果两个目录都不存在，则项目使用持续原生生成，原生项目在构建时重新生成——完全跳过此部分和“清除裸工作流缓存”。

如果升级需要原生变更：

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 版本的发布说明
• 如果使用 Expo SDK 54 或更高版本，请确保安装了 react-native-worklets——这是 react-native-reanimated 正常工作所必需的
• 在 SDK 54+ 中启用 React 编译器，方法是在 app.json 中添加 "experiments": { "reactCompiler": true }——它已稳定且推荐使用
• 从 app.json 中删除 sdkVersion，让 Expo 自动管理它
• 从 package.json 中移除隐含的包：@babel/core、babel-preset-expo、expo-constants
• 如果 babel.config.js 只包含 ‘babel-preset-expo’，则删除该文件
• 如果 metro.config.js 只包含 expo 默认值，则删除该文件

已弃用的包

迁移已弃用的包时，请在移除旧包前更新所有代码用法。对于 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 配置选项：

• resolver.unstable_enablePackageExports 在 SDK +53 中默认启用。
• experimentalImportSupport 在 SDK +54 中默认启用。
• EXPO_USE_FAST_RESOLVER=1 在 SDK +54 中已移除。
• cjs 和 mjs 扩展名在 SDK +50 中默认受支持。
• 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 仅支持新架构。