Skip to main content

版本控制策略

本页面描述了我们对 react-native 软件包遵循的版本控制策略。

¥This page describes the versioning policy we follow for the react-native package.

我们会通过手动和自动测试对每个版本的 React Native 进行全面测试，以确保质量不会下降。

¥We test each version of React Native thoroughly, both with manual and automated tests, to ensure the quality doesn't regress.

React Native 的 stable 通道遵循下文所述的 0.x.y 发布策略。

¥The stable channel of React Native follows the 0.x.y release policy described below.

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

¥React Native also offers a nightly release channel to encourage early feedback on experimental features.

本页面描述了我们对 react-native 以及 @react-native 范围内软件包的版本号处理方法。

¥This page describes our approach to version numbers for react-native and for packages under the @react-native scope.

稳定发布版本​

¥Stable Release Versions

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

¥React Native releases stable versions at a regular cadence.

我们遵循 0.x.y 版本控制方案：

¥We follow the 0.x.y versioning schema:

  • 重大变更将在新的次要版本中发布，即增加 x 号（例如：从 0.78.0 到 0.79.0）。

    ¥Breaking changes will be shipped in a new minor version, i.e. we increment the x number (e.g.: 0.78.0 to 0.79.0).

  • 新的功能和 API 也将在新的次要版本中发布，即我们递增 x 数字（例如：从 0.78.0 到 0.79.0）。

    ¥New features and APIs will also be shipped in a new minor version, i.e. we increment the x number (e.g.: 0.78.0 to 0.79.0).

  • 关键错误修复将在新的补丁版本中发布，即我们增加了 y 值（例如：从 0.78.1 到 0.78.2）。

    ¥Critical bug fixes will be shipped in a new patch version, i.e. we increment the y number (e.g.: 0.78.1 to 0.78.2).

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

¥Stable releases are shipped regularly, with the latest tagged as latest on NPM.

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

¥A series of releases under the same minor number is called a minor series (e.g. 0.76.x is the minor series for 0.76.0, 0.76.1, 0.76.2, etc.).

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

¥You can read more about our commitment to stability in the releases page.

重大变更​

¥Breaking changes

重大变更会给所有人带来不便，我们正努力将其影响降至最低。我们在每个稳定版本中发布的所有重大更改都将高亮：

¥Breaking changes are inconvenient for everyone, and we’re trying to minimize them to the bare minimum. All the breaking changes we ship in each stable release will be highlighted in:

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

¥For each breaking change we’re committed to explaining the reasoning behind it, provide a replacement API if possible, and minimize the impact on final users.

什么是重大变更？​

¥What is a breaking change?

我们认为这些更改对 React Native 来说是重大更改：

¥We consider a breaking change for React Native:

  • 不兼容的 API 变更（即，某个 API 被更改或删除，导致你的代码由于该变更而无法再编译/运行）。示例：

    ¥An incompatible API change (i.e. an API that is changed or removed so that your code won’t compile/run anymore due to that change). Examples:

    • 任何 JS/Java/Kotlin/Obj-c/C++ API 的更改，这些更改需要修改你的代码才能编译。

      ¥Changes of any JS/Java/Kotlin/Obj-c/C++ APIs that would require your code to be changed in order to compile.

    • @react-native/codegen 内部不向后兼容的更改。

      ¥Changes inside @react-native/codegen that are not backward compatible.

  • 一项重大的行为/运行时变更。示例：

    ¥A significant behavior/runtime change. Example:

    • 属性的布局逻辑发生了巨大变化。

      ¥The layout logic of a prop is changed drastically.

  • 开发体验的重大改进。示例：

    ¥A significant change in the development experience. Example:

    • 调试功能已完全移除。

      ¥A debugging feature is entirely removed.

  • 任何传递依赖的重大改进。示例：

    ¥A major bump of any of our transitive dependencies. Examples:

    • React 从 18.x 升级到 19.x

      ¥Bumping React from 18.x to 19.x

    • Android 目标 SDK 版本从 34 升级到 35。

      ¥Bumping the Target SDK on Android from 34 to 35).

  • 我们支持的任何平台版本的缩减。示例：

    ¥A reduction of any of our supported platform versions. Examples:

    • Android 最低 SDK 版本从 21 升级到 23

      ¥Bumping min SDK on Android from 21 to 23

    • iOS 最低版本升级到 15.1。

      ¥Bumping the min iOS version to 15.1.

我们认为这些更改并非重大更改：

¥We don’t consider those changes to be breaking:

  • 修改以 unstable_ 前缀开头的 API：这些 API 公开了实验性功能，我们对它们的最终形态尚不确定。通过以 unstable_ 为前缀发布这些组件，我们可以更快地迭代并更快地获得稳定的 API。

    ¥Modifying APIs starting with unstable_ prefix: These APIs expose experimental features, and we are not confident on their final shape. By releasing these with an unstable_ prefix, we can iterate faster and get to a stable API sooner.

  • 私有或内部 API 的更改：这些 API 通常以 internal_ 或 private_ 为前缀，或者位于 internal/ 或 private/ 文件夹/包中。虽然由于工具限制，其中一些 API 可能具有公共可见性，但我们不认为它们是我们公共 API 的一部分，因此我们将在不另行通知的情况下更改它们。

    ¥Changes to private or internal APIs: These APIs are often prefixed with either internal_ , private_ or living inside a internal/ or private/ folder/package. While some of those APIs might have public visibility due to tooling constraints, we don’t consider them part of our public API, so we’ll be changing them without previous notice.

    • 同样，如果你访问内部属性名称，例如 __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED 或 __reactInternalInstance$uk43rzhitjg，则无法保证。你需要自行处理。

      ¥Similarly, If you access internal property names like __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED or __reactInternalInstance$uk43rzhitjg, there are no guarantees. You are on your own.

    • 使用 @FrameworkAPI 注释的类也被视为内部类。

      ¥Classes annotated with @FrameworkAPI are also considered internal

  • 工具/开发 API 的变更：React Native 的一些公共 API 保留用于与框架和其他工具集成。例如，某些 Metro API 或 React Native DevTools API 应该仅供其他框架或工具使用。这些 API 的更改会直接与受影响的工具讨论，不被视为重大更改（我们不会在发布博文中广泛地传达这些更改）。

    ¥Changes to tooling/development APIs: Some public APIs of React Native are reserved for integration with frameworks and other tools. For example, some of the Metro APIs or React Native DevTools APIs are supposed to be used only by other frameworks or tools. Changes to those APIs are discussed directly with the affected tools and are not considered breaking changes (we won’t be communicating them broadly in the release blogposts).

  • 开发警告：由于警告不会影响运行时行为，我们可能会在任何版本之间添加新的警告或修改现有的警告。

    ¥Development warnings: Since warnings don’t affect runtime behavior, we may add new warnings or modify existing warnings in between any versions.

如果我们预计某个变更会在社区中引发广泛问题，我们仍将尽力为生态系统提供循序渐进的迁移路径。

¥If we expect a change to cause broad problems in the community, we will still do our best to provide a gradual migration path for the ecosystem.

弃用周期​

¥Deprecation Cycles

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

¥As we keep on developing and evolving React Native, we write new APIs and sometimes we need to deprecate existing ones. Those APIs will go through a deprecation cycle.

API 弃用后，该 API 仍可用于后续稳定版本。

¥Once an API is deprecated, it will remain available also for the following stable releases.

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

¥For example: if an API is deprecated in React Native 0.76.x, it will still be available in 0.77.x and won’t be removed sooner than React Native 0.78.x.

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

¥Sometimes we decide to keep a deprecated API for a longer time, if we feel that the ecosystem needs more time to migrate away from it. For those APIs we generally provide warnings to help users migrate away from them.

发布渠道​

¥Release channels

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

¥React Native relies on a thriving open source community to file bug reports, open pull requests, and submit RFCs. To encourage feedback we do support several release channels.

注意

本节与使用框架、库或开发工具的开发者最为相关。主要使用 React Native 构建面向用户应用的开发者无需担心除最新版之外的其他发布版本。

¥This section will be most relevant to developers who work on frameworks, libraries, or developer tooling. Developers who use React Native primarily to build user-facing applications should not need to worry about release channels other than latest.

latest​

latest 适用于稳定的、语义化版本的 React Native 版本。它是你从 npm 安装 React Native 时得到的。这是你今天正在使用的通道。直接使用 React Native 的面向用户的应用使用此渠道。

¥latest is for stable, semver React Native releases. It’s what you get when you install React Native from npm. This is the channel you’re already using today. User-facing applications that consume React Native directly use this channel.

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

¥We publish a newer minor series of React Native regularly, and we update the latest tag to reflect the latest stable version.

next​

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

¥Before we declare a new React Native release stable, we publish a series of release candidate, starting from RC0. Those versions are pre-release versions (following the versioning schema 0.79.0-rc.0) and are tagged as next on NPM.

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

¥When a new branch cut happens, and RCs start to get published on NPM and GitHub, it’s a good idea to test your library/framework against a next version of React Native.

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

¥That will ensure that your project will keep on working well with the upcoming versions of React Native.

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

¥However, do not use prereleases/RCs in user-facing applications directly as they’re not considered production ready.

nightly​

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

¥We also publish a nightly release channel. Nightlies are published every day starting from the main branch of facebook/react-native. Nightlies are considered unstable versions of React Native and are not recommended for production use.

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

¥Nightlies follow the versioning schema as 0.80.0-nightly-<DATE>-<SHA> where <DATE> is the date of the nightly and <SHA> is the SHA of the commit that was used to publish this nightly.

夜间版本仅供测试之用，我们不保证不同夜间版本之间的行为不会发生变化。它们不遵循我们用于最新/下一个版本所使用的语义版本协议。

¥The nightly releases are provided for testing purposes only, and we provide no guarantees that behavior won’t change between nightlies. They do not follow the semver protocol that we use for releases from latest/next.

最好设置一个持续集成 (CI) 工作流程，每天针对 react-native@nightly 版本测试你的库，以确保你的库能够在未来版本中继续正常工作。

¥It is a good idea to set up a CI workflow to test your library against a react-native@nightly version every day, to make sure your library will keep on working with future releases.