SuperAPI AI 工具集

upgrading-expo

编程与开发

查看项目

更新于 10-16 02:17

技能介绍

用途:该技能用于指导开发者升级 Expo SDK 版本并修复相关依赖问题,面向 React Native / Expo 项目的版本迁移场景。

主要能力:

  • 提供分步升级流程:使用 npx expo install expo@latest 与 npx expo install --fix 升级 Expo 及依赖。
  • 诊断与缓存清理:运行 npx expo-doctor,使用 npx expo export -p ios --clear,删除 node_modules 与 .expo,执行 watchman watch-del-all。
  • 破坏性变更检查清单:检查已移除 API、更新模块导入路径、审查需要预构建的原生模块变更、测试相机/音频/视频功能、验证导航。
  • 原生变更预构建:npx expo prebuild --clean 重新生成 ios 与 android 目录;裸工作流需清理 CocoaPods 缓存(cd ios && pod install --repo-update)、Xcode derived data(npx expo run:ios --no-build-cache)、Gradle 缓存(cd android && ./gradlew clean)。
  • 日常维护建议:查看目标 SDK 版本的发布说明;SDK 54+ 需安装 react-native-worklets;通过 app.json 的 "experiments": { "reactCompiler": true } 启用 React Compiler;删除 app.json 中的 sdkVersion;从 package.json 移除隐式包 @babel/core、babel-preset-expo、expo-constants;若 babel.config.js 仅含 babel-preset-expo 则删除;若 metro.config.js 仅含 expo 默认项则删除。
  • 已弃用包替代方案: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 渐变。
  • 补丁与工具配置:检查 patches/ 目录中过时补丁并在不再需要时移除;SDK 53 起可省略 autoprefixer 并使用 postcss.config.mjs;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 仅支持新架构。

参考文档:

  • ./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 安装与迁移指南。

适用场景:需要将已有 Expo 项目升级到较新 SDK 版本,处理依赖冲突、原生构建配置和 API 破坏性变更的开发者。

限制:资料未提供具体的版本兼容性矩阵、错误案例与回滚步骤;部分内容依赖具体 SDK 版本前提,使用前应结合官方发布说明确认。