跳到主要内容

版本策略

本页面描述了我们针对 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 等的次要系列）。

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

重大变更​

重大变更对每个人来说都很不方便，我们正努力将它们降至最低。我们在每个稳定版本中发布的所有重大变更都将突出显示在

  • React Native 更新日志的*“重大变更”*和*“已移除”*部分
  • 每个发布博客文章的*“重大变更”*部分

对于每个重大变更，我们承诺解释其背后的原因，如果可能提供替代 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 用于稳定、semver 的 React Native 发布。它就是您从 npm 安装 React Native 时所获得的版本。这是您今天已在使用的渠道。直接使用 React Native 的面向用户应用程序使用此渠道。

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

下一个​

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

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

这将确保您的项目能够继续与即将发布的 React Native 版本良好配合。

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

夜间版​

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

夜间版遵循版本方案 0.80.0-nightly-<DATE>-<SHA>，其中 <DATE> 是夜间版的日期，<SHA> 是用于发布此夜间版的提交的 SHA。

夜间版发布仅用于测试目的，我们不保证夜间版之间的行为不会改变。它们不遵循我们用于最新/下一个版本的 semver 协议。

建议每天设置 CI 工作流来测试您的库与 react-native@nightly 版本，以确保您的库将继续适用于未来的版本。