跳到主要内容

版本控制策略

本页描述了我们为 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）。
  • 关键 bug 修复将在新的补丁版本中发布，即我们增加 y 的数字（例如：0.78.1 到 0.78.2）。

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

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

稳定承诺​

为了支持用户升级 React Native 版本，我们承诺维护最新的 3 个次要系列（例如，当 0.78 是最新发布版本时，维护 0.78.x、0.77.x 和 0.76.x）。

对于这些发布版本，我们将定期发布更新和 bug 修复。

您可以在 react-native-releases 工作组 阅读更多关于我们支持策略的信息。

重大变更​

重大变更对每个人都不方便，我们正努力将其减至最低。我们在每个稳定发布版本中发布的所有重大变更都将在以下部分突出显示：

  • [React Native 更新日志](https://github.com/facebook/react-native/blob/main/CHANGELOG.md) 中的*重大变更 (Breaking)* 和*已移除 (Removed)* 部分
  • 每个发布博客文章中的*重大变更*部分

对于每个重大变更，我们承诺解释其背后的原因，如果可能，提供替代 API，并将对最终用户的影响降至最低。

什么是重大变更？​

我们认为以下情况属于 React Native 的重大变更：

  • 不兼容的 API 变更（即 API 被更改或移除，导致您的代码因该变更而无法再编译/运行）。示例：
    • 任何 JS/Java/Kotlin/Obj-c/C++ API 的变更，需要修改您的代码才能编译。
    • @react-native/codegen 内部不向后兼容的变更。
  • 显著的行为/运行时变更。示例：
    • 一个属性的布局逻辑发生了剧烈变化。
  • 开发体验的显著变化。示例：
    • 一个调试功能被完全移除。
  • 任何传递性依赖的主要版本升级。示例：
    • 将 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 依靠蓬勃发展的开源社区来提交 bug 报告、打开 Pull Request 和提交 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。

当新的分支剪切发生，并且候选版本开始发布到 NPM 和 GitHub 时，最好针对 next 版本的 React Native 测试您的库/框架。

这将确保您的项目与即将发布的 React Native 版本保持良好的兼容性。

但是，请勿直接在面向用户应用中使用预发布版本/候选版本，因为它们不被视为可用于生产环境。

nightly​

我们还发布一个 nightly 发布渠道。Nightlies 从 facebook/react-native 的 main 分支每天发布。Nightlies 被视为 React Native 的不稳定版本，不建议用于生产环境。

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

Nightly 发布版本仅供测试目的，我们不保证 nightly 之间行为不会改变。它们不遵循我们用于 latest/next 发布版本的 semver 协议。

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