mcpField
U
upgrading-expo

upgrading-expo

github.com/gigs-slc开发359 次安装40 周前更新
代码仓库

关于 upgrading-expo

upgrading-expo 是供开发者升级 Expo SDK 项目的迁移技能，提供升级步骤、诊断和缓存清理方法，并列出各版本的破坏性变更与弃用包检查事项。

主要功能

  1. 01按步骤升级 Expo
  2. 02运行 Expo 诊断
  3. 03清理缓存并重装依赖
  4. 04检查破坏性变更和弃用包
  5. 05处理原生预构建变更

适用场景

  1. 01将项目升级到较新的 Expo SDK
  2. 02诊断依赖升级后的问题
  3. 03为所需的原生变更准备项目

安装

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

$npx skills add https://github.com/gigs-slc/react-native-skills --skill upgrading-expo

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

包含的文件

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

references/
new-architecture.md
react-19.md
react-compiler.md

详细介绍

参考资料

  • ./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 设置和迁移指南

分步升级流程

  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
  • 更新已移动模块的导入路径
  • 检查需要预构建的原生模块变更
  • 测试所有相机、音频和视频功能
  • 确认导航仍能正常工作

针对原生变更进行预构建

如果升级需要原生变更：

npx expo prebuild --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

整理工作

  • 在 https://expo.dev/changelog 查看目标 SDK 版本的发行说明
  • 如果使用 Expo SDK 54 或更高版本，请确保已安装 react-native-worklets——这是 react-native-reanimated 正常运行所必需的。
  • 在 app.json 中添加 "experiments": { "reactCompiler": true }，以在 SDK 54 及更高版本中启用 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 渐变

移除补丁

检查 patches/ 目录中是否有过时的补丁。如果不再需要，请将其移除。

Postcss

  • SDK +53 中不需要 autoprefixer。
  • 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。

新架构

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

评论

支持 Markdown