SuperAPI AI 工具集

upgrading-expo

通用与其它

查看项目

更新于 10-16 09:50

技能介绍

用途:帮助开发者将 Expo 项目升级到新 SDK 版本,并修复升级带来的依赖与破坏性变更问题。资料以指南和参考文档形式组织,覆盖 SDK 53、54、55 的迁移要点。

主要能力与内容:

  • 参考文档:新架构迁移(SDK 53)、React 19 变更(useContext→use、Context.Provider→Context、移除 forwardRef)、React Compiler 配置与迁移、原生标签变化(SDK 55,Icon/Label/Badge 经 NativeTabs.Trigger.* 访问),以及将音频/视频从 expo-av 迁移到 expo-audio 与 expo-video 的指南。
  • 分步升级:先执行 npx expo install expo@latest,再执行 npx expo install --fix,运行 npx expo-doctor 诊断,最后清缓存并重装。
  • 缓存清理:npx expo export -p ios --clear、rm -rf node_modules .expo、watchman watch-del-all。
  • 破坏性变更检查:核对移除的 API、更新移动模块的导入路径、检查需预构建的原生模块、测试相机/音频/视频、验证导航。
  • 预构建:先确认项目是否存在 ios/ 与 android/ 目录;若都不存在则使用 CNG,跳过预构建与裸工作流缓存清理。需要原生变更时执行 npx expo prebuild --clean。
  • 裸工作流清缓存:iOS 执行 cd ios && pod install --repo-update;Xcode 执行 npx expo run:ios --no-build-cache;Android 执行 cd android && ./gradlew clean。
  • 整理事项:查阅 https://expo.dev/changelog 发布说明;SDK 54+ 需安装 react-native-worklets 以支持 react-native-reanimated;SDK 54+ 可在 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;AsyncStorage→expo-sqlite/localStorage/install;expo-app-loading→expo-splash-screen;expo-linear-gradient→experimental_backgroundImage + View 的 CSS 渐变。迁移时先更新所有代码用法再移除旧包。
  • expo.install.exclude:检查 package.json 中被排除的包,升级后评估是否仍需排除。
  • 补丁与 PostCSS:检查 patches/ 中过时补丁并移除;SDK 53+ 不再需要 autoprefixer,改用 postcss.config.mjs。
  • Metro:SDK 53 默认启用 resolver.unstable_enablePackageExports;SDK 54 默认启用 experimentalImportSupport 并移除 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 版本;未来版本将默认启用。
  • 新架构:默认启用,app.json 中 "newArchEnabled": true 不再需要;SDK 53 起 Expo Go 仅支持新架构。

适用场景:需要跨 SDK 版本升级 Expo 应用、处理依赖与 API 变更、迁移废弃包、清理缓存及原生工程的开发者。

限制:资料未提供具体价格、收费方式、支持平台清单及效果承诺,均暂未提供;部分命令涉及原生构建环境,执行前需自行确认项目类型与目录结构。