前言¶
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/。
