前言¶
React Native 项目跟 Expo SDK 时，版本一跨往往不只是改 package.json：expo install --fix 之后 peer 依赖对不上、废弃包还在用、Metro/Babel 配置和 SDK 默认行为不一致，再叠一层 iOS/Android 缓存或 prebuild，很容易在本地和 CI 里各报一套错。自己翻 changelog 和论坛能搞定，但步骤分散，Agent 也容易漏掉 Hermes、New Architecture 或 expo-av 迁移这类跨版本事项。
expo-upgrade 是 Expo 团队在 expo/skills 仓库里维护的官方 Agent Skill（MIT，当前 skill 元数据版本 1.0.0），把 SDK 升级、依赖冲突处理、废弃包替换和缓存清理写成 Agent 可执行的检查清单与分步说明。文档、CLI 仍是事实来源；Skill 负责让 Agent 按同一套顺序应用这些规则。
这是什么¶
- 名称：
expo-upgrade - 描述：Guidelines for upgrading Expo SDK versions and fixing dependency issues（指导 Expo SDK 版本升级与修复依赖问题）
- 来源：plugins/expo/skills/expo-upgrade
- 归属：Expo 官方 Expo Skills 套件中的 Framework（开源）类 Skill，与
expo-overview、expo-router等并列；复杂任务可先加载expo-overview再路由到本 Skill。
核心功能¶
下面介绍 Skill 正文里已写明、可核对的能力范围。
分步升级流程¶
官方建议顺序大致为：
- 升级 Expo 与依赖
- 运行
npx expo-doctor做诊断 - 按需清缓存并重装
node_modules
稳定版示例：
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
Beta/Preview 使用 .preview 后缀（如 55.0.0-preview.2），通过 @next 发布；可通过 exp.host API 查看 expoVersion 是否含 -preview。安装 beta：
npx expo install expo@next --fix
Skill 还强调版本跳跃与 Hermes：若从 SDK 55 及更早升级，应跳过 SDK 56、直接升到 SDK 57，且不要使用 expo@57.0.8 及以下；SDK 55 在启用 Hermes V1、SDK 56、以及较早的 SDK 57 在配合 react-native-worklets 或 react-native-reanimated 时存在 Hermes V1 内存回归，应升级到 expo@57.0.9 或更高。
按 SDK 版本的专题参考¶
Skill 通过 references/ 挂载分版本迁移说明，例如：
| 参考文件 | 对应主题 |
|---|---|
react-19.md |
SDK +54：React 19（useContext → use、Context.Provider → Context、forwardRef 移除等） |
new-architecture.md |
SDK +53：New Architecture 迁移 |
react-compiler.md |
SDK +54：React Compiler 配置与迁移 |
native-tabs.md |
SDK +55：Native tabs（Icon/Label/Badge 经 NativeTabs.Trigger.* 访问） |
expo-av-to-audio.md / expo-av-to-video.md |
SDK +55：expo-av → expo-audio / expo-video |
react-navigation-to-expo-router.md |
SDK +56：@react-navigation/* 迁到 expo-router 入口（codemod + 手工映射） |
Agent 在碰到对应 breaking change 时应加载这些参考，而不是只改版本号。
Breaking changes 与原生工作流¶
检查清单包括：对照 release notes 查移除的 API、更新被移动的 import、审查需要 prebuild 的原生模块变更，并测试相机/音视频与导航。
先判断项目形态：若根目录不存在 ios/ 与 android/，项目使用 Continuous Native Generation（CNG），原生工程在构建时生成，可跳过 prebuild 与「bare workflow 清缓存」整节。
若升级需要原生变更：
npx expo prebuild --clean
会重新生成 ios、android 目录；需确认项目不是不应被覆盖的 bare workflow 误用场景。
当存在 ios/ 或 android/ 时，Skill 列出额外步骤：iOS 侧 pod install --repo-update、npx expo run:ios --no-build-cache；Android 侧 ./gradlew clean。
废弃包、配置与 housekeeping¶
Skill 提供废弃包对照表（如 expo-av → expo-audio / expo-video，expo-permissions → 各包独立权限 API，expo-app-loading → expo-splash-screen 等），并要求先改代码再删旧包；expo-av 迁移需把 Audio.Sound / Audio.Recording / Video 等换成 useAudioPlayer、useAudioRecorder、VideoView + useVideoPlayer。
其他维护项包括：
- 阅读目标 SDK 的 Expo changelog
- 将
AGENTS.md等文件中docs.expo.dev/versions/链接 bump 到新 SDK - SDK 54+ 安装
react-native-worklets（Reanimated 需要）；可在app.json加"experiments": { "reactCompiler": true } - 从
app.json删除sdkVersion，由 Expo 管理 - 使用
expo-router时保留expo-constants为直接依赖 - 检查
package.json里expo.install.exclude、删除过时的patches/ - SDK +53 起 PostCSS：移除不需要的
autoprefixer，优先postcss.config.mjs - Metro：SDK +53/+54 起多项 resolver/import 默认已开启；Expo webpack 已废弃，应迁到 Expo Router + Metro web
New Architecture 在默认已启用，app.json 里 "newArchEnabled": true 不再需要；Expo Go 自 SDK +53 起仅支持新架构。Skill 明确不要引导用户自行切换 Hermes V1 开关——偏离 SDK 默认不受支持。
反馈¶
遇到 Skill 内容错误或过时，可提交可操作的反馈：
npx --yes submit-expo-feedback@latest --category skills --subject "expo-upgrade" "<actionable feedback>"
若 Agent 反复失败、需人工接手，官方建议改用 expo-skill-feedback skill 的 eval-candidate 流程，而非重复上述命令。
安装与启用¶
Expo Skills 可通过插件市场或 skills CLI 安装；expo-upgrade 包含在 expo/skills 仓库中。
Cursor、OpenCode、GitHub Copilot、Windsurf 等（skills CLI）：
在项目根目录执行：
npx skills@latest add expo/skills --skill '*'
只装全部 Expo skill、不绑定特定 agent 时，上述命令即可；也可加 --agent <agent> 指定目标。安装后重启或刷新 Agent 会话以便发现 SKILL.md。
更新：
npx skills@latest update
单 skill：
npx skills@latest update expo-upgrade
Claude Code（官方插件市场）：
claude plugin install expo@claude-plugins-official
或在 Claude Code 内：/plugin install expo@claude-plugins-official。
Codex（OpenAI curated 市场）：
codex plugin add expo@openai-curated
或在 Codex /plugins 中安装 expo。
Claude Code 与 Codex 的插件安装通过各自市场更新；CLI 安装用 npx skills@latest update。
典型用法¶
安装并完成会话刷新后，用自然语言触发即可。官方 expo/skills README 中的示例包括：
- “Help me upgrade this app to the latest Expo SDK.”
Agent 会根据任务描述与 skill 的 description 选择 expo-upgrade，再按 Skill 中的步骤执行安装、doctor、缓存、prebuild 判断与废弃包检查；涉及 SDK 53–56 的专题时，应结合 references/ 下的迁移文档。
可与 Expo MCP server 配合：MCP 提供读文档、npx expo install、EAS 等 live 能力；Skill 规定升级时哪些约束和顺序必须遵守。expo 插件会为 Claude Code/Codex 自动配置 MCP；其他 Agent 见官方 MCP 设置指南。
适用场景与注意¶
适合谁
- 维护 Expo / React Native 应用、需要跨多个 SDK minor 升级的开发者
- 在 Cursor 等 Agent 里做升级，希望减少漏步骤、漏 peer、漏
expo-av/ Router 迁移的情况 - 团队需要在
AGENTS.md里统一文档版本链接与升级后检查项
限制与注意
- Skill 是指令文本，不替代
expo-doctor、changelog 和本地真机测试；音视频、导航、原生模块仍须按 Breaking Changes Checklist 自测 - Hermes V1 与 SDK 57 版本号约束以 Skill 正文为准，勿用未支持的 Worklets Bundle Mode 作为生产方案
- CNG 与 bare workflow 清缓存/prebuild 分支不同，误跑
prebuild --clean可能不符合项目预期 - 内容随 Expo 发布演进，发现问题应通过官方 feedback 或
expo-skill-feedback上报
结尾¶
expo-upgrade 把 Expo SDK 升级从「查文档 + 碰运气」收敛成 Agent 可跟的步骤、版本专题和 housekeeping 清单，适合作为升级任务时的首选 Framework Skill。官方路径：github.com/expo/skills/tree/main/plugins/expo/skills/expo-upgrade；套件总览与安装说明见 github.com/expo/skills 与 docs.expo.dev/skills/。
