參考文件
- ./references/react-19.md -- SDK +54：React 19 變更（useContext → use、Context.Provider → Context、forwardRef 移除）
- ./references/new-architecture.md -- SDK +53：新架構遷移指南
- ./references/react-compiler.md -- SDK +54：React Compiler 設定與遷移指南
- ./references/native-tabs.md -- SDK +55：原生標籤頁變更（Icon/Label/Badge 現在透過 NativeTabs.Trigger.* 存取）
- ./references/expo-av-to-audio.md -- SDK +55：音訊播放與錄製從 expo-av 遷移至 expo-audio
- ./references/expo-av-to-video.md -- SDK +55：影片播放從 expo-av 遷移至 expo-video
- ./references/react-navigation-to-expo-router.md -- SDK +56：將
@react-navigation/*導入遷移至expo-router入口點（codemod + 手動對應）
Beta/預覽版本
Beta 版本使用 .preview 後綴（例如：55.0.0-preview.2），並以 @next 標籤發布。
檢查最新版本是否為 Beta：https://exp.host/--/api/v2/versions（在 expoVersion 中尋找 -preview）
npx expo install expo@next --fix # 安裝 Beta 版本
逐步升級流程
如果您從 SDK 55 或更早版本升級，請跳過 SDK 56，直接升級到 SDK 57。請勿使用
[email protected]或更低版本。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
- 更新已移動模組的導入路徑
- 檢視需要 prebuild 的原生模組變更
- 測試所有相機、音訊和影片功能
- 確認導航功能仍正常運作
原生變更的 Prebuild
首先檢查專案中是否存在 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
後續清理
- 檢視目標 SDK 版本的發行說明：https://expo.dev/changelog
- 更新代理程式指令檔案（
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中加入 `