expo-upgrade

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

References

参考资料

./references/react-19.md -- SDK +54: React 19 changes (useContext → use, Context.Provider → Context, forwardRef removal)
./references/new-architecture.md -- SDK +53: New Architecture migration guide
./references/react-compiler.md -- SDK +54: React Compiler setup and migration guide
./references/native-tabs.md -- SDK +55: Native tabs changes (Icon/Label/Badge now accessed via NativeTabs.Trigger.*)
./references/expo-av-to-audio.md -- SDK +55: Migrate audio playback and recording from expo-av to expo-audio
./references/expo-av-to-video.md -- SDK +55: Migrate video playback from expo-av to expo-video
./references/react-navigation-to-expo-router.md -- SDK +56: Migrate
```
@react-navigation/*
```
imports to
```
expo-router
```
entry points (codemod + manual mapping)

./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
```
入口（代码转换工具 + 手动映射）

Beta/Preview Releases

Beta/预览版本

Beta versions use

.preview

suffix (e.g.,

55.0.0-preview.2

), published under

@next

tag.

Check if latest is beta: https://exp.host/--/api/v2/versions (look for

-preview

expoVersion

)

bash

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

Beta版本使用

.preview

后缀（例如：

55.0.0-preview.2

），发布在

@next

标签下。

检查最新版本是否为Beta：https://exp.host/--/api/v2/versions（查看

expoVersion

中是否包含

-preview

）

bash

npx expo install expo@next --fix  # 安装Beta版本

Step-by-Step Upgrade Process

分步升级流程

Upgrade Expo and dependencies

bash

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

Run diagnostics:
```
npx expo-doctor
```
Clear caches and reinstall

bash

npx expo export -p ios --clear
rm -rf node_modules .expo
watchman watch-del-all

升级Expo及依赖

bash

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

运行诊断：
```
npx expo-doctor
```
清除缓存并重新安装

bash

npx expo export -p ios --clear
rm -rf node_modules .expo
watchman watch-del-all

Breaking Changes Checklist

破坏性变更检查清单

Check for removed APIs in release notes
Update import paths for moved modules
Review native module changes requiring prebuild
Test all camera, audio, and video features
Verify navigation still works correctly

查看发行说明中已移除的API
更新已迁移模块的导入路径
检查需要预构建的原生模块变更
测试所有相机、音频和视频功能
验证导航功能是否正常工作

Prebuild for Native Changes

针对原生变更的预构建

First check if
ios/
and
android/
directories exist in the project. If neither directory exists, the project uses Continuous Native Generation (CNG) and native projects are regenerated at build time — skip this section and "Clear caches for bare workflow" entirely.

If upgrading requires native changes:

bash

npx expo prebuild --clean

This regenerates the

ios

and

android

directories. Ensure the project is not a bare workflow app before running this command.

**首先检查项目中是否存在

ios/

和

android/

目录。**如果两个目录都不存在，说明项目使用持续原生生成（CNG），原生项目会在构建时重新生成——请完全跳过本节和“裸工作流清除缓存”部分。

如果升级需要原生变更：

bash

npx expo prebuild --clean

此命令会重新生成

ios

和

android

目录。运行此命令前，请确保项目不是裸工作流应用。

Clear caches for bare workflow

裸工作流清除缓存

These steps only apply when

ios/

and/or

android/

directories exist in the project:

Clear the cocoapods cache for iOS:
```
cd ios && pod install --repo-update
```
Clear derived data for Xcode:
```
npx expo run:ios --no-build-cache
```
Clear the Gradle cache for Android:
```
cd android && ./gradlew clean
```

以下步骤仅适用于项目中存在

ios/

和/或

android/

目录的情况：

清除iOS的CocoaPods缓存：
```
cd ios && pod install --repo-update
```
清除Xcode的派生数据：
```
npx expo run:ios --no-build-cache
```
清除Android的Gradle缓存：
```
cd android && ./gradlew clean
```

Housekeeping

后续整理

Review release notes for the target SDK version at https://expo.dev/changelog
If using Expo SDK 54 or later, ensure react-native-worklets is installed — this is required for react-native-reanimated to work.
Enable React Compiler in SDK 54+ by adding
```
"experiments": { "reactCompiler": true }
```
to app.json — it's stable and recommended
Delete sdkVersion from
```
app.json
```
to let Expo manage it automatically

Remove implicit packages from

package.json

@babel/core

babel-preset-expo

expo-constants

If the babel.config.js only contains 'babel-preset-expo', delete the file
If the metro.config.js only contains expo defaults, delete the file

在 https://expo.dev/changelog 查看目标SDK版本的发行说明
如果使用Expo SDK 54或更高版本，请确保已安装react-native-worklets——这是react-native-reanimated正常工作的必要条件
在SDK 54+中，通过在app.json中添加
```
"experiments": { "reactCompiler": true }
```
启用React Compiler——该功能已稳定，建议启用
删除app.json中的sdkVersion，让Expo自动管理

从package.json中移除隐含包：

@babel/core

、

babel-preset-expo

、

expo-constants

如果babel.config.js仅包含'babel-preset-expo'，请删除该文件
如果metro.config.js仅包含Expo默认配置，请删除该文件

Deprecated Packages

已弃用的包

Old Package	Replacement
`expo-av`	`expo-audio` and `expo-video`
`expo-permissions`	Individual package permission APIs
`@expo/vector-icons`	`expo-symbols` (for SF Symbols)
`AsyncStorage`	`expo-sqlite/localStorage/install`
`expo-app-loading`	`expo-splash-screen`
expo-linear-gradient	experimental_backgroundImage + CSS gradients in View

When migrating deprecated packages, update all code usage before removing the old package. For expo-av, consult the migration references to convert Audio.Sound to useAudioPlayer, Audio.Recording to useAudioRecorder, and Video components to VideoView with useVideoPlayer.

旧包名	替代方案
`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组件转换为搭配useVideoPlayer的VideoView。

expo.install.exclude

Check if package.json has excluded packages:

json

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

Exclusions are often workarounds that may no longer be needed after upgrading. Review each one.

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

json

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

排除项通常是临时解决方法，升级后可能不再需要，请逐一检查。

Removing patches

移除补丁

Check if there are any outdated patches in the

patches/

directory. Remove them if they are no longer needed.

检查

patches/

目录中是否有过时的补丁。如果不再需要，请移除它们。

Postcss

```
autoprefixer
```
isn't needed in SDK +53. Remove it from dependencies and check
```
postcss.config.js
```
or
```
postcss.config.mjs
```
to remove it from the plugins list.
Use
```
postcss.config.mjs
```
in SDK +53.

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

Metro

Remove redundant metro config options:

resolver.unstable_enablePackageExports is enabled by default in SDK +53.
```
experimentalImportSupport
```
is enabled by default in SDK +54.
```
EXPO_USE_FAST_RESOLVER=1
```
is removed in SDK +54.
cjs and mjs extensions are supported by default in SDK +50.
Expo webpack is deprecated, migrate to Expo Router and Metro web.

移除冗余的Metro配置项：

resolver.unstable_enablePackageExports在SDK +53中默认启用。
```
experimentalImportSupport
```
在SDK +54中默认启用。
```
EXPO_USE_FAST_RESOLVER=1
```
在SDK +54中已移除。
SDK +50中默认支持cjs和mjs扩展名。
Expo webpack已弃用，请迁移至Expo Router和Metro web。

Hermes engine v1

Hermes引擎v1

Since SDK 55, users can opt-in to use Hermes engine v1 for improved runtime performance. This requires setting

useHermesV1: true

in the

expo-build-properties

config plugin, and may require a specific version of the

hermes-compiler

npm package. Hermes v1 will become a default in some future SDK release.

从SDK 55开始，用户可以选择使用Hermes引擎v1以提升运行时性能。这需要在

expo-build-properties

配置插件中设置

useHermesV1: true

，并且可能需要特定版本的

hermes-compiler

npm包。Hermes v1将在未来某个SDK版本中成为默认选项。

New Architecture

新架构

The new architecture is enabled by default, the app.json field

"newArchEnabled": true

is no longer needed as it's the default. Expo Go only supports the new architecture as of SDK +53.

新架构已默认启用，app.json中的

"newArchEnabled": true

字段不再需要，因为它已是默认值。从SDK +53开始，Expo Go仅支持新架构。