upgrading-expo

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

References

参考资料

./references/new-architecture.md -- SDK +53: New Architecture migration guide
./references/react-19.md -- SDK +54: React 19 changes (useContext → use, Context.Provider → Context, forwardRef removal)
./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 -- Migrate audio playback and recording from expo-av to expo-audio
./references/expo-av-to-video.md -- Migrate video playback from expo-av to expo-video

./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 Compiler配置与迁移指南
./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

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  # install 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

针对原生变更的预构建

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.

如果升级需要原生变更：

bash

npx expo prebuild --clean

这将重新生成

ios

和

android

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

Clear caches for bare workflow

裸工作流的缓存清理

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的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

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

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

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中已移除。
cjs和mjs扩展名在SDK +50中默认支持。
Expo webpack已弃用，请迁移至Expo Router和Metro web。

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

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