SDK 升级不是只改 package.json 中的一个数字。Expo、React Native、原生模块、导航入口和构建工具需要配套，旧补丁或临时排除项也可能影响结果。expo-upgrade 把这些检查串起来，适合先评估路径，再在可回退的改动中逐步迁移。
先把 Expo 知识接入 Agent
Codex 用户在终端运行下面的 Expo 官方插件命令，也可在 Codex 的 /plugins 中找到 Expo。Claude Code 用户改用 claude plugin install expo@claude-plugins-official。两种插件都会带入 Expo Skills 与 MCP 配置；其他支持 Agent Skills 的客户端可用 npx skills@latest add expo/skills --skill '*'，按提示选择客户端并刷新会话。安装插件本身不会构建或发布应用。
codex plugin add expo@openai-curated
打开已有 Expo 项目，直接说“使用 expo-upgrade”，并给出当前 SDK、目标平台及相关文件。
先记录当前项目，而不是直接追 latest
以下是可按项目调整的首次输入：
使用 expo-upgrade 检查这个项目的升级路径。先列出当前 SDK、React Native、原生目录维护方式、补丁和依赖排除项，再根据目标版本发布说明制定步骤。不要直接清空原生目录；逐步对齐依赖，运行 doctor，并验证登录、导航、相机与音视频。
让 Agent 读取依赖、锁文件、应用配置和原生目录，说明哪些由工具生成、哪些有人手动维护。记录现有测试和关键功能基线，尤其是相机、音频、视频与导航。已有补丁不代表都该删除，依赖排除项也可能仍有原因，应逐项判断。
官方升级总指南通常建议按版本递进，而当前 Skill 对部分旧 SDK 另有具体例外：它针对 Hermes V1 相关内存回归，给出跳过 SDK 56、使用 SDK 57 指定修复版本或更新版本的说明。不要只记“逐级升级”或“直接最新版”一条口号；应让 Agent 同时核对目标发布说明和当前技能里的版本条件。
对齐依赖并解决真实诊断
确定目标后，按目标版本更新 Expo 包，再运行 npx expo install --fix 和 npx expo-doctor。诊断报告指出缺少 peer dependency 时，应补齐或重新评估刚移除的包，而不是因为它过去是间接依赖就认定不需要。项目使用的包管理器和锁文件应保持一致。
API 迁移需要找到实际使用点，先替换调用再移除旧依赖。例如音视频库更名不仅改变包名，还可能改变组件与 Hook 的使用方式。导航入口和 Babel、Metro 配置也应结合版本处理，避免把别的 SDK 的写法混进来。
原生项目决定下一步
生成式原生目录可以按官方流程重新生成；手动维护的原生项目则需要保留本地改动，并参考对应升级差异。不要把清缓存、删除目录和重装依赖作为不加诊断的第一步，它们可能掩盖根因，也不能替代迁移代码。
完成后重新构建需要更新的原生包，再走一遍登录、导航、媒体和平台权限流程。Expo Go 能打开某个页面，不足以证明生产开发包中的原生依赖已匹配。期望产物包括明确的版本变化、处理过的弃用项、诊断结果与尚待设备确认的事项；只有这些都与目标一致，升级才算有可判断的结束点。
用版本矩阵管理迁移
升级前把 Expo SDK、React Native、Expo Router、主要原生库和构建配置写在一张表里，加一列记录“当前是否实际使用”。让 Agent 对照目标版本的发布说明，逐项标记需要更新包、改 API、重建原生项目还是只需验证。这样可以避免一看到旧依赖就删除，也能防止已经不用的临时补丁继续掩盖问题。
升级后不要只凭 doctor 通过就结束。先运行现有测试，再在开发构建上检查登录、深链接、相机/音视频与推送等项目真正用到的能力。若有手改的 ios 或 android 目录，保留差异并专门审查；自动重新生成目录可能抹掉这些改动。最后记录未能在设备上验证的功能，留给发布前检查。
每一步都留下可回退的边界
先单独提交或保存升级前状态，再按依赖、配置、代码迁移、原生构建分阶段处理。每阶段记录改动与诊断结果，发现故障时能知道是哪个环节引入。升级路径受当前版本影响，技能里关于某些 SDK 的例外不能脱离项目版本直接套用。对已有用户的应用，尤其要检查数据迁移、权限请求和通知跳转；这些问题在新装应用上可能不出现。
版本跳跃不顺时拆成可复盘的阶段
一位 Expo 用户直接从 SDK 54 升到 56 后问题难以定位，后来按 54→55→56 分段推进，并用 Claude Code 与 Expo Skills 推荐的升级 Agent 对齐依赖；真正耗时的是 iOS 的 Swift 6 与 JSI 问题。这个例子提醒你保存每一阶段的诊断和原生构建结果。它不是所有项目都必须逐版升级的规则；先按目标版本发布说明检查是否有明确的跳版例外。