upgrade-react-native

升级 React Native

通过获取并应用 React Native Upgrade Helper 中的差异，将 React Native Community CLI 项目升级到目标版本。

说明

Expo 用户： 对于 Expo 项目或更复杂的升级场景，请尝试：

• expo/skills/upgrading-expo
• callstackincubator/agent-skills/upgrading-react-native

调用

/upgrade-react-native <targetVersion>

• <targetVersion> — 要升级到的 React Native 版本（例如 0.79.0）。

分步流程

按顺序执行以下每个步骤。不要跳过任何步骤。

1. 检测当前 React Native 版本

读取项目根目录下的 package.json，并从 dependencies（或 devDependencies）中提取 react-native 版本。 去除任何 semver 范围前缀（^、~、>= 等），以获取精确的当前版本字符串。

如果无法确定当前版本，请停止并询问用户。

2. 验证目标版本

• 目标版本必须是有效的 semver 字符串（例如 0.79.0）。
• 目标版本必须高于当前版本。
• 通过以下方式验证目标版本是否存在：

  https://raw.githubusercontent.com/react-native-community/rn-diff-purge/master/RELEASES
  

  获取此文件并确认其中列出了目标版本。如果没有，请报告最接近的可用版本，并请用户选择。

3. 获取升级差异

获取两个版本之间的统一差异：

https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/<currentVersion>..<targetVersion>.diff

例如，要从 0.73.0 升级到 0.74.0：

https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/0.73.0..0.74.0.diff

如果无法获取差异（404），可能是因为没有对应的精确补丁版本。请尝试最接近的次要版本（例如使用 0.73.0 代替 0.73.2）。报告尝试过的版本，并在需要时询问用户。

4. 解析差异并映射文件路径

差异中使用的模板项目名称为 RnDiffApp。将差异中的所有路径映射到实际项目：

差异路径前缀	实际项目路径
RnDiffApp/	项目根目录（./）

此外，将模板标识符替换为项目的实际名称：

模板值	替换为
RnDiffApp	项目的应用名称（来自 app.json → name，或 package.json 中的 name 字段）
rndiffapp	项目应用名称的小写形式
com.rndiffapp	项目的 Android 包名（来自 android/app/build.gradle 或 android/app/src/main/AndroidManifest.xml）

5. 审查差异并制定变更计划

进行任何编辑之前，审查完整差异并对变更分类：

1. 直接应用 — 项目中存在且原始内容与差异中的 - 行匹配的文件。可直接应用。
2. 冲突 — 项目内容与模板不同的文件（自定义修改）。需要手动合并。
3. 新文件 — 差异中有但项目中尚不存在的文件。创建这些文件。
4. 已删除文件 — 差异中要删除的文件。仅当项目没有向这些文件添加自定义内容时才删除。

继续操作之前，先向用户展示此计划。按类别对变更分组：

• 根配置文件（package.json、metro.config.js、.eslintrc.js 等）
• iOS 原生文件（ios/ 目录）
• Android 原生文件（android/ 目录）
• JavaScript/TypeScript 源文件（如果任何模板源文件发生了变更）
• 第三方原生依赖（来自步骤 7 — 包括在该步骤中识别出的版本升级）

6. 应用更改

按照步骤 5 中的计划应用更改：

• 对于直接应用：编辑文件，使其与差异中的 + 行一致。
• 对于冲突：应用升级更改，同时保留项目的自定义内容。请自行判断如何合并。如有疑问，请展示两个版本并询问用户。
• 对于新文件：在映射后的路径创建文件。
• 对于已删除文件：删除这些文件。

重要注意事项：

• 更新 package.json 时，请更新 react-native 版本以及差异中提及的任何相关依赖（例如 react、@react-native/* 包、Gradle 版本、CocoaPods 版本）。
• 请勿自动运行 npm install / yarn install / pod install。升级后请告知用户需要执行这些步骤。
• 有关特定版本的破坏性更改和迁移说明，请参阅 references 部分。

7. 更新第三方原生依赖

检查项目 package.json 中的 dependencies 和 devDependencies，找出包含原生代码的第三方 React Native 库（即包含 ios/ 或 android/ 目录，或已知的原生模块）。常见示例包括 react-native-screens、react-native-reanimated、react-native-gesture-handler、@react-native-async-storage/async-storage、react-native-svg、react-native-safe-area-context 等。

针对每个候选依赖：

1. 从其 GitHub 仓库或 npm 页面获取该库的 README。
2. 查找 React Native 版本兼容性表或相关章节——许多原生库会说明其不同版本分别支持哪些 React Native 版本（例如“Compatibility”或“Version Support”表格）。
3. 如果 README 中有兼容性表，将目标 React Native 版本映射到特定库版本，则在升级计划中包含该库的版本升级。
4. 如果 README 未说明与 React Native 版本的兼容性，则跳过该库；不要猜测或假设需要升级。

在步骤 5 中基于差异的更改旁，列出所有建议的依赖升级，并归入 Third-party native dependencies 部分。每项请：

• 说明当前版本、建议版本，并链接到找到的兼容性信息。
• 如果有多个主版本兼容，请优先选择支持目标 React Native 版本的最新稳定版。

在步骤 6 中将这些版本升级应用到 package.json。

8. 迁移到 Strict TypeScript API（目标版本 >= 0.87）

React Native 0.87 将 Strict TypeScript API 设为默认。当升级跨越此边界（当前版本 < 0.87，目标版本 >= 0.87）且项目使用 TypeScript（存在 tsconfig.json）时，类型检查会受到影响，因此必须执行此步骤；不得悄悄跳过。

询问用户希望采用哪种方式：

1. 立即迁移（推荐）——运行 migrate-to-strict-api 技能（/migrate-to-strict-api），该技能会处理依赖兼容性、深层导入重写和已知的类型破坏性更改。
2. 暂缓并使用临时退出选项——在 tsconfig.json 的 compilerOptions 中添加 "customConditions": ["react-native", "react-native-legacy-deep-imports"]，保留两个条目。告知用户此退出选项只是临时措施，将在未来版本中移除。

如果目标版本低于 0.87，或项目未使用 TypeScript，则跳过此步骤，不要主动建议迁移。

9. 升级后检查清单

应用所有更改后，向用户提供以下检查清单：

• 运行 npm install 或 yarn install 以更新 JS 依赖项
• 运行 cd ios && bundle exec pod install（或 npx pod-install）以更新 iOS 原生依赖项
• 对 Android 执行干净构建：cd android && ./gradlew clean
• 对 iOS 执行干净构建：cd ios && xcodebuild clean
• 在两个平台上运行应用，确认其可以启动
• 运行项目的测试套件
• [ ]（TypeScript，目标版本 >= 0.87）运行 npx tsc --noEmit，确认 Strict TypeScript API 迁移成功，或选择退出步骤 8
• 检查冲突解决方案是否正确
• 查看 React Native 更新日志，了解其他不兼容变更
• 查看 Upgrade Helper 网页界面，了解补充说明

参考资料

请参考以下资料，了解特定版本的迁移指南：

• references/upgrade-helper-api.md — 如何 以编程方式获取差异和版本列表
• migrate-to-strict-api — Strict TypeScript API 迁移的配套技能（从 0.87 起默认启用）