upgrading-react-native

upgrading-react-native 技能概览

这个技能做什么

upgrading-react-native 技能可以帮你规划并执行 React Native 版本升级，比泛泛的提示词更少靠猜。它聚焦的是实际工作：选择正确的升级路径、应用 rn-diff-purge / Upgrade Helper 的差异、对齐依赖项，以及处理那些最常让构建失败的 iOS 和 Android 变更。

适合谁用

如果你在 React Native 应用里做 Frontend Development，需要从一个 RN 版本升级到另一个，尤其是会涉及原生目录、CocoaPods、Gradle 或 Expo SDK 兼容性时，就适合用 upgrading-react-native 技能。它最适合需要可重复升级流程的维护者，而不是只想得到一次性“把版本号改掉”答案的人。

它为什么有用

它的核心价值在于工作流指导：帮你梳理升级顺序，把应用级改动和依赖工作分开，并尽早发现常见故障点。当你的目标是升级一个真正包含原生代码的现有应用，而不只是改 package.json 时，它的作用最明显。

如何使用 upgrading-react-native 技能

安装并触发它

使用 agent skill 命令走 upgrading-react-native install 流程：
npx skills add callstackincubator/agent-skills --skill upgrading-react-native

然后用提示词调用它，并带上当前版本、目标版本、应用结构以及任何特殊约束。例如：“使用 upgrading-react-native 技能，把我们的 monorepo 应用从 RN 0.76.9 升级到 0.78.2。应用在 apps/mobile，使用 Expo，并且 iOS 和 Android 构建都必须保持绿色。”

提供正确的输入

这个技能在你提供以下信息时效果最好：

• 当前 React Native 版本和目标版本
• 这是 Expo 还是 bare RN
• 仓库形态：单应用还是 monorepo
• 包管理器和原生构建配置
• 已知阻碍，比如自定义原生模块、CodePush 或严格的 CI 规则

如果你只说“升级 RN”，输出会过于泛泛。把版本、应用路径和约束写清楚后，技能才能更准确地映射差异和依赖决策。

先读这些文件

在使用 upgrading-react-native 时，先从这些文件开始：

• SKILL.md，了解升级顺序
• references/upgrade-helper-core.md，了解基于 diff 的工作流
• references/monorepo-singlerepo-targeting.md，如果应用不在仓库根目录
• references/upgrading-dependencies.md，检查包兼容性
• references/expo-sdk-upgrade.md，如果项目里用了 Expo
• references/upgrade-verification.md，做升级后的验证

这个阅读顺序很重要，因为它能避免一个常见失败模式：在目标应用和依赖范围还没理清之前，就先套用升级 diff。

实用工作流

一份成熟的 upgrading-react-native 指南通常会按这个节奏推进：

1. 确认应用包和准确的 RN 版本
2. 获取相关模板 diff
3. 更新包依赖和配套包
4. 应用 iOS 与 Android 的原生配置改动
5. 运行构建和验证检查
6. 处理首次执行后暴露出来的 API 破坏或测试失败

把这个技能当作结构化升级助手，而不是构建测试的替代品。它的输出应该帮助你按正确顺序修改正确的文件。

upgrading-react-native 技能 FAQ

它比普通提示词更好吗？

如果升级会碰到原生代码、多个包，或者 Expo 兼容性问题，答案是肯定的。普通提示词能在理论上告诉你该怎么做；upgrading-react-native 技能更擅长组织真实的升级路径，并先把你应该检查的文件和验证项摆出来。

它适用于 Expo 应用吗？

适用，但只能作为整体升级流程的一部分。如果你的应用包里用了 expo，就应该把这个技能和 Expo 升级层一起使用，因为 Expo 的版本对齐和 expo install --fix 可能会改变依赖规划。

对新手友好吗？

新手也能用，但你仍然需要基础的仓库识读能力：知道 package.json、ios/ 和 android/ 在哪里，以及如何运行构建。这个技能能减少升级时的歧义，但不能替代你去验证平台构建和应用行为。

什么时候不该用它？

如果你只是做纯 JavaScript 重构，或者实际上并没有更换 React Native 版本，就不该依赖它。它也不适合你想要一个不带仓库上下文的通用迁移聊天，因为它的价值来自基于版本、基于文件的升级指导。

如何改进 upgrading-react-native 技能

提供带版本和范围的输入

最能提升效果的做法，是明确写出起始版本、目标版本和应用范围。例如：0.75.4 -> 0.78.2、apps/mobile、Expo SDK 51、npm。这样技能就能把重点放在正确的 diff、包对齐和验证步骤上，而不是给你一堆泛泛建议。

先把难点说出来

如果你知道应用里有自定义原生模块、workspace 结构，或者一些容易出问题的依赖，在请求升级方案之前就先说明。这能帮助 upgrading-react-native 技能优先做兼容性检查，避免推荐不适合你技术栈的改动。

要求按文件输出升级计划

更好的结果来自要求具体顺序的提示词，而不是只要解释。比如：“列出要修改的文件、要执行的命令，以及这个升级的操作顺序。” 这样得到的输出才方便你实际执行和审查。

第一轮后继续迭代

拿到第一版升级计划后，把失败信息反馈回去：diff 冲突、pod install 报错、Gradle 问题、类型错误或测试失败。最好的 upgrading-react-native 方案本来就是迭代式的；第二轮通常正是技能把问题收敛到具体平台或具体包的地方。