upgrading-expo

upgrading-expo skill 概覽

upgrading-expo skill 的用途

upgrading-expo skill 能協助你規劃並執行 Expo SDK 升級，比起泛泛的「我該怎麼升級 Expo？」提示，更能減少盲點。它聚焦在真正需要處理的工作：更新核心套件、修正相依版本漂移、清除殘留快取，以及提早發現 React、New Architecture、Native Tabs 與 expo-av 遷移相關的常見破壞性變更。

誰適合使用 upgrading-expo

這個 upgrading-expo skill 特別適合前端開發者、React Native 團隊，以及維護既有 Expo app 的 AI 代理。當你手上已經有專案、需要一條可實際執行的升級路徑，而不只是看 release notes 摘要時，它最有價值。

最適合的情境包括：

• 在較新的 Expo SDK 版本之間升級
• 執行 expo install --fix 後，處理安裝或執行期故障
• 從已變更或拆分的套件遷移，例如 expo-av
• 確認 React 19 或 Native Tabs 這類 SDK 特定變更是否會影響你的程式碼庫

真正要解決的事情

評估 upgrading-expo for Frontend Development 的使用者，通常都想快速得到這三個問題的答案：

1. 我第一步該跑哪些指令？
2. 哪些破壞性變更最可能打到我的 app？
3. 在浪費時間除錯前，我應該先檢查哪些檔案或程式模式？

這個 skill 的價值，在於它把這些判斷集中整理在同一處，並且連到具體的遷移參考資料。

它和一般升級提示有什麼不同

一般提示可能只會建議你「升級 Expo 然後跑 doctor」。upgrading-expo skill 更進一步，會從 repository 中帶出和版本直接相關的遷移主題，包括：

• SDK 53+ 的 New Architecture 預設行為
• SDK 54 的 React 19 變更
• SDK 54+ 的 React Compiler 設定
• SDK 55 的 Native Tabs API 變更
• expo-av 在音訊與影片上的替代遷移路徑

因此，對於有明確目標的升級工作來說，它比泛用的 React Native 疑難排解提示更合適。

安裝前你該先知道的事

這個 skill 偏重提供指引，而不是自動化。它不會附帶可直接掃描你 repo 的腳本。它的價值來自整理好的升級流程，以及你可以套用到自己程式碼庫的參考文件。如果你要的是一鍵式 migrator，那它不是這種工具；但如果你要的是高訊號、帶有具體遷移範例的升級清單，它就很適合。

如何使用 upgrading-expo skill

upgrading-expo 的安裝方式

如果你的 AI 環境支援 Skills，請安裝 Expo skills repository，並從其中呼叫 upgrading-expo。常見做法如下：

npx skills add https://github.com/expo/skills --skill upgrading-expo

如果你的工具鏈使用不同的 skill loader，請指向這個 repo 路徑：
plugins/expo/skills/upgrading-expo

先從正確的 repository 檔案看起

若要實際使用 upgrading-expo，建議依照這個順序閱讀：

1. SKILL.md
2. references/new-architecture.md
3. references/react-19.md
4. references/react-compiler.md
5. references/native-tabs.md
6. references/expo-av-to-audio.md
7. references/expo-av-to-video.md

這個閱讀順序對應最常見的升級卡點：先看架構與 React 的變動，再看功能層級的遷移。

先跑 upgrading-expo 的核心升級流程

這個 skill 提供的基礎升級流程很短，但非常值得在深入除錯前先照做一次：

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

這樣做的重要性在於：

• expo@latest 會先對齊 SDK 版本
• --fix 會校正 Expo 管理的套件版本
• expo-doctor 能提早抓出相容性問題
• 清除快取可移除舊的 Metro / native 狀態，避免它們偽裝成升級 bug

如果你在 Linux 上，或根本沒有使用 Watchman，請依你的環境調整清理步驟。

什麼時候該用 preview 版本

這個 skill 也有記錄 Expo beta build 的做法，也就是使用 @next 之下帶有 .preview 的版本。如果你要驗證即將推出的 SDK，或測試尚未進到 stable 的修正，這會很有用。

npx expo install expo@next --fix

但請務必在有意識的情況下才這麼做。除非你就是要試用 pre-release，否則對正式產品 app 來說，preview 升級不應該是預設選項。

提供 upgrading-expo 真正需要的輸入資訊

要讓 upgrading-expo guide 發揮效果，關鍵在於你要交代清楚目前狀態與目標狀態。請提供：

• 目前的 Expo SDK 版本
• package manager
• 你使用 Expo Go 還是 development builds
• 是否有跑 prebuild
• 關鍵套件：expo-router、expo-av、react-native-reanimated、自訂 native modules
• 目前安裝、建置或執行期出現的錯誤
• iOS、Android 或 web 是否有平台特定故障

少了這些背景，輸出通常就會停留在很泛的建議。

把模糊需求改寫成高品質提示

弱提示：

Upgrade my Expo app.

較強的提示：

Use the upgrading-expo skill to move my app from Expo SDK 53 to 54. We use expo-router, expo-av, Reanimated, and development builds. After npx expo install --fix, expo-doctor reports dependency mismatches and our app fails on startup with video playback errors. Tell me the likely breaking changes, the commands to run in order, and the code areas I should inspect first.

這樣寫的原因是：

• 它清楚指出來源與目標 SDK
• 它列出高風險套件
• 它要求的是有優先順序的輸出，而不是泛泛建議

把你的 app 對應到 upgrading-expo 的參考指南

這個 repository 的參考文件，只有在你刻意對照自己的相依套件面時才最有價值：

• 用 expo-av 處理聲音或錄音？看 references/expo-av-to-audio.md
• 用 expo-av 處理影片？看 references/expo-av-to-video.md
• 升級到 SDK 55，且使用 expo-router/unstable-native-tabs？看 references/native-tabs.md
• 升到 SDK 53+ 或 54+，而且有 native modules？看 references/new-architecture.md
• 使用 SDK 54？請同時查看 references/react-19.md 和 references/react-compiler.md

這正是這個 skill 比起快速瀏覽 repo 更有資訊增益的地方。

留意 upgrading-expo 指出的高風險升級區域

實務上，這些是 skill 最常指出的斷點：

• SDK 升級後的套件版本不一致
• 舊版 native modules 與 New Architecture 不相容
• Reanimated 設定變更，包括 SDK 54+ 的 react-native-worklets
• app 或函式庫程式碼中的 React 19 API 變動
• expo-av 遷移到 expo-audio 與 expo-video
• Native Tabs 在 router 層的 UI 變更

如果你的 app 有用到這些，請要求 skill 產出聚焦的遷移清單，而不是一般性的升級摘要。

用兩階段 workflow 來跑 upgrading-expo

一個好的 upgrading-expo 使用模式是：

1. 先根據你的版本與相依套件，請它做升級計畫
2. 實際執行指令
3. 把精確錯誤貼回去，請它縮小範圍提出修復方案

當你能帶回 expo-doctor、TypeScript、Metro 或 native build 的具體輸出時，這個 skill 會更擅長做結構化分流與排查。

檢查 upgrading-expo 暗示的 release note 類型問題

這個 skill 的破壞性變更清單，實際上是在提醒你優先檢查這些地方：

• 被移除的 API
• 已變更的 import path
• 需要 prebuild 的 native module 變更
• camera、audio、video 的退化問題
• navigation 退化問題

也就是說，你的 code review 不應該只停在 package.json。在跑 app 之前，就應先搜尋程式碼庫裡受影響的 imports 與 components。

在 prebuild 與 native code 專案中使用 upgrading-expo 要更謹慎

如果你的 app 有自訂 native modules 或 config plugins，upgrading-expo skill 依然有幫助，但你要預期會有一部分工作超出 markdown 參考文件的範圍。在這類專案中，建議要求 skill 明確分開：

• 只牽涉 JS 的遷移工作
• 需要重新產生 prebuild 的工作
• native 相依套件相容性檢查

這樣拆開，能降低升級過程中的混淆。

upgrading-expo skill 常見問題

upgrading-expo 適合新手嗎？

適合，前提是你已經有一個 Expo 專案，並且能提供基本專案資訊。它不是完整的 Expo 教學，而是聚焦升級的指南；因此新手如果能提供目前 SDK 版本、錯誤訊息與主要相依套件，通常會得到更好的結果。

upgrading-expo skill 的邊界在哪裡？

這個 skill 擅長處理升級規劃、指令順序與已知遷移熱點，但不會自動檢查你整個 repo，也無法保證每個第三方 native library 都完全相容。若遇到較深層的 native 故障，你仍可能需要去看套件專屬文件與 GitHub issues。

upgrading-expo 和直接叫 LLM 幫我升級 Expo 有何不同？

主要差異在於整理與導向。upgrading-expo skill 會把模型引導到 Expo 專屬的遷移參考資料上，而一般提示很容易漏掉這些內容，尤其是 expo-av、React 19、React Compiler、Native Tabs 與 New Architecture 相關行為。

什麼情況下不該用 upgrading-expo？

以下情況可以跳過它：

• 你是在建立全新的 Expo app，而不是升級現有 app
• 你的問題和 SDK 升級無關
• 你需要的是自動化 codemod 或 CLI 遷移工具
• 你的主要卡點是某一個第三方 native library，而且它有自己獨特的遷移步驟

upgrading-expo 有涵蓋 preview SDK 嗎？

有。這個 skill 有提到 beta release 會使用 .preview 後綴，並透過 @next 安裝。這對測試即將到來的變更很有幫助，但若是一般穩定升級，stable 版本仍然是更安全的預設選擇。

upgrading-expo 只適用於 managed workflow app 嗎？

不是。它同時適用於 managed 與以 prebuild 為基礎的 Expo app；只是當你使用 prebuild 或自訂 native code 時，更有可能還需要額外做手動相容性檢查。

如何提升 upgrading-expo skill 的效果

清楚提供 upgrading-expo 的版本跨度

最有價值的改進其實很簡單：直接寫「從 SDK X 升到 SDK Y」，不要只說「升級 Expo」。因為當你跨到 SDK 53、54 或 55 時，遷移建議的內容會有明顯差異。

補上會改變答案的套件面資訊

想讓 upgrading-expo 給出更好的結果，請補上會觸發參考文件的關鍵套件：

• expo-av
• expo-router
• react-native-reanimated
• 自訂 native modules
• 任何在 expo-doctor 中出錯的套件

這樣 skill 才能從泛用清單，進一步縮小到較可能影響你的實際建議。

貼上真實診斷資訊，不要只做口語轉述

不佳：

build failed after upgrade

較好：

npx expo-doctor says package versions are invalid, Metro reports unresolved import from expo-av, and iOS dev build fails after enabling New Architecture.

精確的 log 能幫助 skill 區分：到底是相依版本漂移，還是 API 遷移問題。

要求有優先順序的輸出

一個很實用的請求格式是：

1. 現在該跑的指令
2. 依機率排序的可能故障點
3. 應該搜尋的檔案／imports
4. 修正後的驗證步驟

這種結構能讓 upgrading-expo guide 在時間壓力下更容易照著執行。

把安裝失敗和程式碼遷移分開處理

常見失敗模式之一，就是把套件安裝問題和原始碼層級的 API 變更混在一起。建議要求 skill 依序處理：

• 相依版本對齊
• doctor 輸出
• 快取重置
• 原始碼遷移
• 執行期驗證

這能減少來回打轉的除錯。

要求提供針對程式碼庫的搜尋模式

提升 upgrading-expo skill 輸出的最好方法之一，就是請它直接列出 grep 風格的搜尋目標。例如：

Using the upgrading-expo skill, list the import paths, component names, and hooks I should search for to migrate from expo-av and to verify Native Tabs changes in SDK 55.

這能把大方向建議轉成可以直接執行的 code review 任務。

第一次升級後，優先驗證高風險路徑

完成第一輪升級嘗試後，請特別測試：

• 音訊播放與錄音
• 影片播放
• tab navigation
• 在 Expo Go 與 dev build 的啟動情況
• 任何大量使用動畫或 native modules 的畫面

這些正是最容易暴露 SDK 過渡問題、也是 skill 特別涵蓋的區域。

用更聚焦的後續提示反覆收斂

不要每次都要求 skill 重新解整個升級問題。第二輪提示應該縮小範圍，例如：

• 「只聚焦我 shared UI package 裡的 React 19 變更」
• 「只聚焦 expo-av 的影片遷移」
• 「只聚焦 New Architecture 不相容問題」

範圍越小，通常越能得到更清楚、也更正確的修復步驟。