跳到主要内容

版本策略

本页面介绍我们遵循的 react-native 包的版本策略。

我们通过手动和自动测试来彻底测试 React Native 的每个版本，以确保质量不会下降。

React Native 的 stable 发布频道遵循下方描述的 0.x.y 发布策略。

React Native 还提供了一个 nightly 发布频道，以鼓励对实验性功能提供早期反馈。

本页面介绍我们针对 react-native 和 @react-native 作用域下包的版本号的处理方法。

稳定发布版本​

React Native 会定期发布稳定版本。

我们遵循 0.x.y 版本模式

  • 破坏性变更将发布在新版次版本中，即我们增加 x 的数字（例如：0.78.0 到 0.79.0）。
  • 新功能和 API 也将发布在新版次版本中，即我们增加 x 的数字（例如：0.78.0 到 0.79.0）。
  • 关键的错误修复将发布在新补丁版本中，即我们增加 y 的数字（例如：0.78.1 到 0.78.2）。

稳定发布会定期发布，NPM 上最新的版本标记为 latest。

同一版次号下的一系列发布被称为一个 **版次系列**（例如 0.76.x 是 0.76.0、0.76.1、0.76.2 等的版次系列）。

您可以在 发布页面 中阅读更多关于我们 **对稳定性的承诺**。

重大变更​

破坏性变更对每个人来说都很不方便，我们正努力将其降至最低。我们在每个稳定发布中发布的所有破坏性变更都将在以下位置突出显示：

对于每一项破坏性变更，我们承诺解释其原因，在可能的情况下提供替代 API，并最大限度地减少对最终用户的影响。

什么是破坏性变更？​

我们将 React Native 的以下变更视为破坏性变更：

  • 不兼容的 API 变更（即 API 被更改或移除，导致您的代码由于该变更而无法编译/运行）。示例：
    • 任何 JS/Java/Kotlin/Obj-c/C++ API 的变更，这些变更会要求您修改代码才能编译。
    • @react-native/codegen 内部的非向后兼容的变更。
  • 重大的行为/运行时变更。示例：
    • 某个 prop 的布局逻辑发生剧烈变化。
  • 开发体验的重大变更。示例：
    • 某个调试功能被完全移除。
  • 任何传递依赖项的主要升级。示例：
    • 将 React 从 18.x 升级到 19.x
    • 将 Android 的目标 SDK 从 34 升级到 35。
  • 支持平台版本的减少。示例：
    • 将 Android 的最低 SDK 从 21 升级到 23
    • 将 iOS 的最低版本升级到 15.1。

我们不认为以下变更属于破坏性变更：

  • 修改以 unstable_ 前缀开头的 API：这些 API 暴露了实验性功能，我们对其最终形态没有信心。通过添加 unstable_ 前缀发布这些 API，我们可以更快地迭代并更快地推出稳定 API。
  • 对私有或内部 API 的更改：这些 API 通常以 internal_、private_ 为前缀，或者位于 internal/ 或 private/ 文件夹/包中。虽然由于工具限制，其中一些 API 可能具有公共可见性，但我们不认为它们是我们公共 API 的一部分，因此我们将更改它们，而无需事先通知。
    • 同样，如果您访问内部属性名称，如 __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED 或 __reactInternalInstance$uk43rzhitjg，则没有保证。您需自担风险。
    • 用 @FrameworkAPI 注释的类也视为内部
  • 对工具/开发 API 的更改：React Native 的一些公共 API 保留用于与框架和其他工具集成。例如，一些 Metro API 或 React Native DevTools API 只能由其他框架或工具使用。这些 API 的更改将直接与受影响的工具讨论，不被视为破坏性更改（我们不会在发布博文中广泛宣传）。
  • 开发警告：由于警告不影响运行时行为，我们可以在任何版本之间添加新的警告或修改现有警告。

如果我们预期某项更改会在社区中引起广泛问题，我们仍将尽最大努力为生态系统提供渐进式的迁移路径。

弃用周期​

随着我们不断开发和演进 React Native，我们编写新的 API，有时需要弃用现有的 API。这些 API 将经历一个弃用周期。

一旦 API 被弃用，它将 **继续** 在 **后续** 的稳定发布版本中可用。

例如：如果一个 API 在 React Native 0.76.x 中被弃用，它仍将在 0.77.x 中可用，并且不会早于 React Native 0.78.x 被移除。

有时，如果我们觉得生态系统需要更多时间迁移，我们会决定将弃用的 API 保留更长时间。对于这些 API，我们通常会提供警告以帮助用户迁移。

发布频道​

React Native 依赖于一个蓬勃发展的开源社区来提交错误报告、打开拉取请求和提交 RFC。为了鼓励反馈，我们支持多个发布频道。

注意

本节对从事框架、库或开发工具的开发者最为相关。主要使用 React Native 构建面向用户的应用程序的开发者通常不需要关心 latest 以外的发布频道。

latest​

latest 用于稳定、符合 semver 的 React Native 发布。这是您从 npm 安装 React Native 时获得的。这是您目前正在使用的频道。直接使用 React Native 的面向用户的应用程序会使用此频道。

我们定期发布新的 React Native 版次系列，并将 latest 标签更新为最新的稳定版本。

next​

在我们宣布新的 React Native 版本稳定之前，我们发布一系列**发布候选版本**，从 RC0 开始。这些版本是预发布版本（遵循版本模式 0.79.0-rc.0），并在 NPM 上标记为 next。

当发生新的分支切割，并且 RCs 开始在 NPM 和 GitHub 上发布时，将您的库/框架与 React Native 的 next 版本进行测试是一个好主意。

这将确保您的项目能够与 React Native 的未来版本良好兼容。

然而，请勿在面向用户的应用程序中直接使用预发布/RC 版本，因为它们不被认为是生产就绪的。

nightly​

我们还发布了一个 nightly 发布频道。Nightlies 每天从 facebook/react-native 的 main 分支开始发布。Nightlies 被认为是 React Native 的不稳定版本，不推荐用于生产环境。

Nightlies 遵循版本模式 0.80.0-nightly-<DATE>-<SHA>，其中 <DATE> 是 nighty 的日期，<SHA> 是用于发布此 nighty 的提交的 SHA。

Nightly 发布仅用于测试目的，我们不对 nightlies 之间的行为变更提供任何保证。它们不遵循我们用于 latest/next 发布所使用的 semver 协议。

最好设置一个 CI 工作流，每天针对 react-native@nightly 版本测试您的库，以确保您的库能够与未来版本保持兼容。