React Native 升级指南：使用 upgrade-react-native 技能轻松升级项目版本

upgrade-react-native by react-native-community/skills

329 周安装量

14 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/react-native-community/skills --skill upgrade-react-native

开发自动化 React

🇨🇳中文介绍

升级 React Native

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

[!Note] 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，并从（或）中提取版本。去除任何 semver 范围前缀（、、等）以获取确切的当前版本字符串。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

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. 审查差异并规划更改

在进行任何编辑之前，请审查整个差异并对更改进行分类：

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

在继续之前，将此计划呈现给用户。按区域对更改进行分组：

根配置文件（package.json、metro.config.js、.eslintrc.js 等）
iOS 原生文件（ios/ 目录）
Android 原生文件（android/ 目录）
JavaScript/TypeScript 源代码（如果任何模板源文件发生更改）
第三方原生依赖项（来自步骤 7 — 包括在那里识别的任何版本更新）

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

对于直接应用：编辑文件以匹配差异的 + 行。
对于冲突：应用升级更改，同时保留项目的自定义内容。运用你的判断进行合并。如果不确定，请显示两个版本并询问用户。
对于新文件：在映射的路径处创建它们。
对于已删除文件：删除它们。

重要注意事项：

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

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 等。

对于每个候选依赖项：

从 GitHub 仓库或 npm 页面获取库的 README。
查找 React Native 版本兼容性表或部分 — 许多原生库会记录其包的哪些版本支持哪些 React Native 版本（例如“兼容性”或“版本支持”表）。
如果 README 包含兼容性表，该表将目标 React Native 版本映射到特定的库版本，则在升级计划中包含该库的版本更新。
如果 README 未提及与 React Native 版本的兼容性，则跳过该库 — 不要猜测或假设需要升级。

将所有提议的依赖项更新与步骤 5 中基于差异的更改一起呈现（分组在第三方原生依赖项部分下）。对于每个依赖项：

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

在步骤 6 中，将这些版本更新应用到 package.json。

8. 升级后检查清单

应用所有更改后，向用户呈现一个检查清单：

运行 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
在两个平台上运行应用以验证其能启动
运行项目的测试套件
审查任何冲突解决方案的正确性
查看 React Native 更新日志以了解其他破坏性变更
查看 Upgrade Helper 网页界面以获取任何补充说明

查阅以下内容以获取特定版本的迁移指南：

references/upgrade-helper-api.md — 如何以编程方式获取差异和版本列表

🇺🇸English

Upgrade React Native

Upgrade a React Native Community CLI project to a target version by fetching and applying the diff from the React Native Upgrade Helper.

[!Note] Expo users: For Expo projects or more complex upgrade scenarios, try:

expo/skills/upgrading-expo

callstackincubator/agent-skills/upgrading-react-native

Invocation

/upgrade-react-native <targetVersion>

<targetVersion> — the React Native version to upgrade to (e.g. 0.79.0).

Step-by-step procedure

Follow every step below in order. Do not skip steps.

1. Detect the current React Native version

Read the project's root package.json and extract the react-native version from dependencies (or devDependencies). Strip any semver range prefix (^, ~, >=, etc.) to get the exact current version string.

If the current version cannot be determined, stop and ask the user.

2. Validate the target version

The target version must be a valid semver string (e.g. 0.79.0).
It must be greater than the current version.

Verify the target version exists by checking:

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

Fetch this file and confirm the target version is listed. If not, report the closest available versions and ask the user to choose.

3. Fetch the upgrade diff

Fetch the unified diff between the two versions:

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

For example, to upgrade from 0.73.0 to 0.74.0:

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

If the diff cannot be fetched (404), it may be because exact patch versions are not available. Try the nearest minor versions (e.g. 0.73.0 instead of 0.73.2). Report what you tried and ask the user if needed.

4. Parse the diff and map file paths

The diff uses the template project name RnDiffApp. Map every path in the diff to the actual project:

Diff path prefix	Actual project path
`RnDiffApp/`	Project root (`./`)

Additionally, replace occurrences of the template identifiers with the project's actual names:

Template value	Replace with
`RnDiffApp`	The project's app name (from `app.json` → `name`, or the `name` field in `package.json`)
`rndiffapp`	Lowercase version of the project's app name
`com.rndiffapp`	The project's Android package name (from `android/app/build.gradle` or )

5. Review the diff and plan changes

Before making any edits, review the entire diff and categorize changes:

Direct applies — files that exist in the project and whose original content matches the diff's - lines. These can be applied as-is.
Conflicts — files where the project's content has diverged from the template (custom modifications). These need manual merging.
New files — files in the diff that don't exist in the project yet. Create them.
Deleted files — files the diff removes. Delete them only if the project hasn't added custom content to them.

Present this plan to the user before proceeding. Group changes by area:

Root config files (package.json, metro.config.js, .eslintrc.js, etc.)
iOS native files (ios/ directory)
Android native files (android/ directory)
JavaScript/TypeScript source (if any template source files changed)
Third-party native dependencies (from step 7 — include any version bumps identified there)

6. Apply changes

Apply the changes following the plan from step 5:

For direct applies : edit the file to match the diff's + lines.
For conflicts : apply the upgrade changes while preserving the project's customizations. Use your judgement to merge. If uncertain, show both versions and ask the user.
For new files : create them at the mapped path.
For deleted files : remove them.

Important considerations:

When updating package.json, update the react-native version and any related dependencies mentioned in the diff (e.g. react, @react-native/* packages, Gradle versions, CocoaPods versions).
Do NOT run npm install / yarn install / pod install automatically. Inform the user these steps are needed after the upgrade.
Refer to the references section for version-specific guidance on breaking changes and migration notes.

7. Update third-party native dependencies

Scan the project's dependencies and devDependencies in package.json for third-party React Native libraries that contain native code (i.e. they have an ios/ or android/ directory, or are known native modules). Common examples include react-native-screens, react-native-reanimated, react-native-gesture-handler, @react-native-async-storage/async-storage, react-native-svg, react-native-safe-area-context, etc.

For each candidate dependency:

Fetch the library's README from its GitHub repository or npm page.
Look for a React Native version compatibility table or section — many native libraries document which versions of their package support which React Native versions (e.g. a "Compatibility" or "Version Support" table).
If the README contains a compatibility table that maps the target React Native version to a specific library version, include that library version bump in the upgrade plan.
If the README does not mention version compatibility with React Native versions , skip the library — do not guess or assume an upgrade is needed.

Present all proposed dependency bumps alongside the diff-based changes in step 5 (grouped under a Third-party native dependencies section). For each:

State the current version, the proposed version, and link to the compatibility info you found.
If multiple major versions are compatible, prefer the latest stable version that supports the target React Native version.

Apply these version bumps to package.json as part of step 6.

8. Post-upgrade checklist

After applying all changes, present the user with a checklist:

Run npm install or yarn install to update JS dependencies
Run cd ios && bundle exec pod install (or npx pod-install) to update native iOS dependencies
Run a clean build for Android: cd android && ./gradlew clean
Run a clean build for iOS: cd ios && xcodebuild clean
Run the app on both platforms to verify it launches
Run the project's test suite
Review any conflict resolutions for correctness
Check the React Native changelog for additional breaking changes
Check the Upgrade Helper web UI for any supplementary notes

References

Consult these for version-specific migration guidance:

references/upgrade-helper-api.md — How to fetch diffs and version lists programmatically

Weekly Installs

329

Repository

react-native-co…y/skills

GitHub Stars

First Seen

Feb 11, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

github-copilot320

opencode319

codex319

gemini-cli316

amp313

kimi-cli313

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

138,300 周安装

android/app/src/main/AndroidManifest.xml