前言¶

React Native 版本升級往往要同時動 package.json、iOS Podfile、Android Gradle，還要對照 Upgrade Helper 和 release notes 裏的 breaking change。手工對照容易漏改原生配置，或在第三方庫兼容性上踩坑。Coding Agent 若缺少固定步驟，也容易編造不存在的 diff 或跳過 pod install、雙端構建驗證。

下面介紹 Callstack 在 agent-skills 倉庫中維護的 upgrading-react-native Skill：把「選路徑 → 拉模板 diff → 改依賴 → 對齊 React / Expo → 驗證」寫成可複用的工作流，並引用 rn-diff-purge 等權威來源，減少遺漏與幻覺。

這是什麼¶

upgrading-react-native 是一份面向 Agent 的 Skill 文檔（MIT 許可），由 Callstack 維護，官方目錄爲：

https://github.com/callstackincubator/agent-skills/tree/main/skills/upgrading-react-native

定位：在升級 React Native 時，通過 rn-diff-purge 模板 diff（與 Upgrade Helper 同源思路）、更新 package.json 依賴、遷移 iOS / Android 原生配置、處理 CocoaPods 與 Gradle 變更，並在適用時覆蓋 Expo SDK 層；支持 monorepo 與單倉應用的命令作用域劃分。

官方描述中的觸發場景包括：升級 RN 版本、從 RN 0.x 升到 0.y、以及在 RN 升級同時遷移 Expo SDK。

核心功能¶

Skill 將完整升級流程拆成若干 reference 文檔，由路由文檔決定從哪一步進入。已覈實的能力如下。

典型升級順序¶

1. Route：通過 upgrading-react-native.md 選擇升級路徑。
2. Diff：通過 upgrade-helper-core.md 使用 Upgrade Helper 工作流拉取 canonical 模板 diff。
3. Dependencies：通過 upgrading-dependencies.md 評估並更新第三方包。
4. React：若涉及 React 升級，通過 react.md 對齊版本（含 React 19 相關規則）。
5. Expo（若適用）：通過 expo-sdk-upgrade.md 處理 Expo SDK 層。
6. Verify：通過 upgrade-verification.md 做升級後檢查（含 agent-device 輔助驗證項）。

問題到文檔的映射¶

Quick Reference 文件一覽¶

安裝與啓用¶

在 officialskills.sh 上公佈的安裝方式爲：

npx skills add https://github.com/callstackincubator/agent-skills --skill upgrading-react-native

也可將 Skill 目錄鏈接交給支持 Agent Skills 的編碼助手，由其按項目約定安裝：

https://github.com/callstackincubator/agent-skills/tree/main/skills/upgrading-react-native

資料中未區分 Cursor、Codex CLI、Claude Code 的安裝差異；以你當前工具對 npx skills add 或 SKILL.md 的支持爲準。

典型用法¶

Skill 自帶的 Quick start 演示：先確認當前 RN 版本與 npm 上的 latest，再從 rn-diff-purge 拉取區間 diff，審閱變更文件後安裝依賴並雙端構建。

下面命令摘自官方 SKILL.md（示例區間爲 0.76.9 → 0.78.2；實際升級時請替換爲你的起止版本）。

# 檢測當前版本與遠端 latest
npm pkg get dependencies.react-native --prefix "$APP_DIR"
npm view react-native dist-tags.latest

# 1. 拉取模板 diff（版本號需與目標區間一致）
curl -L -f -o /tmp/rn-diff.diff \
  "https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/0.76.9..0.78.2.diff" \
  && echo "Diff downloaded OK" || echo "ERROR: diff not found, check versions"

# 2. 查看 diff 涉及哪些文件
grep -n "^diff --git" /tmp/rn-diff.diff

# 3. 更新 package.json、按 diff 改原生工程後安裝並重建
npm install --prefix "$APP_DIR"
cd "$APP_DIR/ios" && pod install

# 4. 驗證：Android 與 iOS 模擬器均需能成功構建
npx react-native build-android --mode debug --no-packager
xcodebuild -workspace "$APP_DIR/ios/App.xcworkspace" -scheme App -sdk iphonesimulator build

使用 Agent 時，可先說明當前 RN 版本與目標版本，讓其按 Skill 中的 Route → Diff → Dependencies → React → Expo（如需要）→ Verify 順序執行；diff 拉取失敗時，官方示例會提示檢查版本號是否在 rn-diff-purge 中存在對應區間。

適用場景與注意¶

適合在以下情況引用該 Skill：

• 將 React Native 應用遷移到較新版本。
• 需要對照 Upgrade Helper reconciling 原生配置變更。
• 升級前需要對照 release notes 覈對 breaking change。
• 在 major 版本躍遷後遷移 iOS Podfile、Android Gradle。
• 提交升級前檢查第三方包兼容性。
• 升級後要在 iOS 模擬器與 Android 上跑構建驗證。
• 在 RN 核心升級同時調整 Expo SDK 版本。

注意：

• Skill 是流程與 reference 的編排，不能替代你對業務代碼與私有原生改動的審閱；模板 diff 主要覆蓋官方模板工程差異，自定義模塊仍需手工合併。
• xcodebuild 示例中的 workspace 名、scheme 名（App.xcworkspace / App）需與你的工程一致。
• Monorepo 場景應結合 monorepo-singlerepo-targeting.md 限定 $APP_DIR 與命令前綴，避免在錯誤子包上執行 npm install 或 pod install。

結尾¶

React Native 升級仍是繁瑣但常必要的工作；upgrading-react-native 把 rn-diff-purge、依賴、原生工具鏈與驗證步驟固化成 Agent 可跟隨的清單，價值在於減少跳步和版本幻覺。需要安裝或閱讀完整 SKILL.md 時，見官方倉庫：

https://github.com/callstackincubator/agent-skills/tree/main/skills/upgrading-react-native