SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场expo-upgrading-v55

expo-upgrading-v55

编程与开发

查看项目

更新于 10-27 16:21

技能介绍

用途

本技能为 Expo 框架（开源）项目提供升级到 Expo SDK 57 的指导，并帮助修复升级过程中的依赖问题。技能名称中的 v55 为上游命名，实际内容覆盖 SDK 53 至 SDK 57 的迁移要点。

主要能力

技能包含多份参考文档，覆盖以下主题：

  • React 19 变更（SDK 54+）：useContext → use、Context.Provider → Context、移除 forwardRef。
  • 新架构迁移指南（SDK 53+）。
  • React Compiler 设置与迁移指南（SDK 54+）。
  • 原生标签变更（SDK 55+）：Icon/Label/Badge 现在通过 NativeTabs.Trigger.* 访问。
  • 音频迁移（SDK 55+）：从 expo-av 迁移到 expo-audio。
  • 视频迁移（SDK 55+）：从 expo-av 迁移到 expo-video。
  • 导航迁移（SDK 56+）：将 @react-navigation/* 导入迁移到 expo-router 入口点（含 codemod 与手动映射）。

使用方式

分步升级流程

如果从 SDK 55 或更早版本升级，跳过 SDK 56，直接升级到 SDK 57。不要使用 expo@57.0.8 或更低版本。SDK 55 启用 Hermes V1、SDK 56 以及较早的 SDK 57 版本存在 Hermes V1 内存回归问题，在使用 react-native-worklets 或 react-native-reanimated 时可能大幅增加内存占用。

升级 Expo 与依赖：

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 和 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 版本的发布说明。
  • 更新代理指令文件（AGENTS.md）中的版本文档链接。默认模板链接到 https://docs.expo.dev/versions/v<version>/。搜索 docs.expo.dev/versions/ 并将每个链接升级到新的 SDK 版本。
  • 如果使用 Expo SDK 54 或更高版本，确保安装了 react-native-worklets——这是 react-native-reanimated 正常工作所必需的。
  • 在 SDK 54+ 中启用 React Compiler：在 app.json 中添加 "experiments": { "reactCompiler": true }——它已稳定且推荐使用。
  • 从 app.json 中删除 sdkVersion，让 Expo 自动管理。
  • 从 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 渐变

迁移废弃包时，先更新所有代码用法，再移除旧包。对于 expo-av，请参考迁移文档将 Audio.Sound 转换为 useAudioPlayer、Audio.Recording 转换为 useAudioRecorder、Video 组件转换为带 useVideoPlayer 的 VideoView。

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 配置选项：

  • 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。

Hermes 引擎 v1

Hermes V1 在 SDK 56 及更高版本中为默认。使用 Hermes V1 的 SDK 55 应用、所有 SDK 56 应用，以及 expo@57.0.17 之前的 SDK 57 应用，在导入 react-native-worklets 或 react-native-reanimated 时可能遇到内存回归。请直接升级到 SDK 57 和 expo@57.0.17 或更高版本。不要推荐 Worklets Bundle Mode 作为生产变通方案；它不受支持且为实验性，可能无法按预期工作。

不要引导用户选择启用或禁用 Hermes V1。更改 Hermes 版本与 SDK 默认值不同是不受支持的，并且有重大的构建和依赖管理注意事项。

新架构

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

测试版/预览版

测试版使用 .preview 后缀（例如 55.0.0-preview.2），发布在 @next 标签下。

检查最新版是否为测试版：https://exp.host/--/api/v2/versions（查找 expoVersion 中的 -preview）

npx expo install expo@next --fix  # 安装测试版

提交反馈

如果遇到错误、误导性或过时信息，请报告以便 Expo 改进：

npx --yes submit-expo-feedback@latest --category skills --subject "expo-upgrade" "<actionable feedback>"

仅在你有具体且可操作的内容时提交。尽可能包含相关上下文。如果 AI 代理反复失败或用户不得不接管 Expo 任务，请加载 expo-skill-feedback 技能并遵循其 eval-candidate 流程，而不是重复使用上述命令。

适用场景

适用于需要将 Expo 项目从较早 SDK 版本升级到 SDK 57 的开发者，尤其是涉及 React 19、新架构、React Compiler、NativeTabs、expo-av 迁移、React Navigation 迁移等变更的项目。

限制

技能内容基于所提供资料，未提供的信息（如具体收费、价格、平台支持范围等）暂未提供。