upgrade-react-native

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Upgrade React Native

升级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

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

[!Note] Expo用户注意： 对于Expo项目或更复杂的升级场景，请尝试：

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
```
).

/upgrade-react-native <targetVersion>

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

Step-by-step procedure

分步操作流程

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

请按以下顺序完成每一步，不要跳过任何步骤。

1. Detect the current React Native version

1. 检测当前React Native版本

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.

读取项目根目录下的

package.json

，从

dependencies

（或

devDependencies

）中提取

react-native

版本。去除任何语义化版本范围前缀（

、

>=

等），获取精确的当前版本字符串。

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

2. Validate the target version

2. 验证目标版本

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.

目标版本必须是有效的语义化版本字符串（例如
```
0.79.0
```
）。
它必须高于当前版本。
通过检查以下链接验证目标版本是否存在：
```
https://raw.githubusercontent.com/react-native-community/rn-diff-purge/master/RELEASES
```
获取该文件并确认目标版本已列出。如果未找到，请告知用户最近可用的版本并让其选择。

3. Fetch the upgrade diff

3. 获取升级差异文件

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

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.

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

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. Parse the diff and map file paths

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

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 `android/app/src/main/AndroidManifest.xml` )

差异文件使用模板项目名称

RnDiffApp

。将差异文件中的所有路径映射到实际项目：

差异文件路径前缀	实际项目路径
`RnDiffApp/`	项目根目录 ( `./` )

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

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

5. Review the diff and plan changes

5. 审阅差异文件并规划变更

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)

在进行任何编辑之前，审阅整个差异文件并对变更进行分类：

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

在执行前将此计划告知用户。按区域对变更进行分组：

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

6. Apply changes

6. 应用变更

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.

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

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

重要注意事项：

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

7. Update third-party native dependencies

7. 更新第三方原生依赖

Scan the project's

dependencies

and

devDependencies

package.json

for third-party React Native libraries that contain native code (i.e. they have an

ios/

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.

扫描项目

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

等。

对于每个候选依赖：

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

在步骤5的基于差异的变更之外，将所有提议的依赖升级一并呈现（归类在第三方原生依赖部分下）。对于每个依赖：

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

在步骤6中，将这些版本升级应用到

package.json

。

8. Post-upgrade checklist

8. 升级后检查清单

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

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

运行
```
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网页UI获取补充说明

References

参考资料

Consult these for version-specific migration guidance:

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

如需版本特定的迁移指南，请参考以下内容：

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