前言¶
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 文档，由路由文档决定从哪一步进入。已核实的能力如下。
典型升级顺序¶
- Route：通过
upgrading-react-native.md选择升级路径。 - Diff：通过
upgrade-helper-core.md使用 Upgrade Helper 工作流拉取 canonical 模板 diff。 - Dependencies：通过
upgrading-dependencies.md评估并更新第三方包。 - React：若涉及 React 升级，通过
react.md对齐版本（含 React 19 相关规则）。 - Expo（若适用）：通过
expo-sdk-upgrade.md处理 Expo SDK 层。 - Verify：通过
upgrade-verification.md做升级后检查（含 agent-device 辅助验证项）。
问题到文档的映射¶
| 问题 | 优先打开的 reference |
|---|---|
| 需要升级 React Native | upgrade-helper-core.md |
| 需要依赖风险梳理与迁移方案 | upgrading-dependencies.md |
| 需要 React / React 19 包对齐 | react.md |
| 需要先定工作流路由 | upgrading-react-native.md |
| 需要 Expo SDK 专项步骤 | expo-sdk-upgrade.md |
| 需要手工或 Agent 辅助回归验证 | upgrade-verification.md |
| 需要 monorepo / 单仓命令作用域 | monorepo-singlerepo-targeting.md |
Quick Reference 文件一览¶
| 文件 | 说明 |
|---|---|
upgrading-react-native.md |
路由：选择正确升级路径 |
upgrade-helper-core.md |
Upgrade Helper 核心流程与可靠性检查 |
upgrading-dependencies.md |
依赖兼容性检查与迁移规划 |
react.md |
React 与 React 19 升级对齐规则 |
expo-sdk-upgrade.md |
Expo SDK 升级层（条件适用） |
upgrade-verification.md |
升级后验证清单 |
monorepo-singlerepo-targeting.md |
Monorepo 与单仓 targeting、命令作用域 |
安装与启用¶
在 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
