mcpField
U
upgrading-expo

upgrading-expo

github.com/expo开发3.5k42.2k 次安装今天更新
代码仓库

关于 upgrading-expo

面向 Expo 项目维护者的升级技能，提供依赖更新、诊断和缓存清理步骤，并汇总 SDK 版本变更及弃用包迁移指引。

主要功能

  1. 01Expo 与依赖升级步骤
  2. 02expo-doctor 诊断
  3. 03SDK 版本变更参考
  4. 04弃用包迁移指引
  5. 05原生项目清理说明

适用场景

  1. 01将 Expo 项目升级到最新版本
  2. 02检查升级后的依赖问题
  3. 03迁移已弃用的 Expo 包
  4. 04处理升级所需的原生变更

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/expo/skills --skill upgrading-expo

安装后在 Claude Code 中输入/upgrading-expo确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

agents/
openai.yaml
references/
expo-av-to-audio.md
expo-av-to-video.md
native-tabs.md
new-architecture.md
react-19.md
react-compiler.md
react-navigation-to-expo-router.md

详细介绍

参考资料

  • ./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/Preview 版本

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

逐步升级流程

  1. 升级 Expo 和依赖项
npx expo install expo@latest
npx expo install --fix

  1. 运行诊断：npx expo-doctor

  2. 清理缓存并重新安装

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 版本的发行说明
  • 如果使用 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 默认配置，请删除该文件

已弃用的包

旧包替代方案
expo-avexpo-audio 和 expo-video
expo-permissions各个包的权限 API
@expo/vector-iconsexpo-symbols（用于 SF Symbols）
AsyncStorageexpo-sqlite/localStorage/install
expo-app-loadingexpo-splash-screen
expo-linear-gradientexperimental_backgroundImage + View 中的 CSS 渐变

迁移已弃用的包时，请先更新所有代码用法，再移除旧包。对于 expo-av，请参阅迁移参考资料，将 Audio.Sound 转换为使用 useAudioPlayer，将 Audio.Recording 转换为使用 useAudioRecorder，并将 Video 组件转换为使用 VideoView 和 useVideoPlayer。

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 仅支持新架构。

评论

支持 Markdown