跳至主内容
版本：0.82

版本管理策略

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。 发现错误？ 报告问题 →

本文档阐述我们在 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 更新日志 的 Breaking（重大变更）和 Removed（移除功能）章节

  • 每篇版本发布博客的 Breaking Changes（重大变更）章节

对于每次重大变更，我们承诺说明变更原因，尽可能提供替代 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 通常带有 internal_、private_ 前缀，或位于 internal/、private/ 目录/包中。虽然部分 API 可能因工具限制具有公开可见性，但我们不将其视为公共 API 的一部分，因此会不经事先通知直接修改。

    • 同理，若您访问内部属性名称（如 __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED 或 __reactInternalInstance$uk43rzhitjg），我们不提供任何保证，相关风险需自行承担。
    • 标注 @FrameworkAPI 的类同样视为内部 API

  • 开发工具/调试 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 通道提供符合语义化版本的稳定 React Native 发布版，即通过 npm 安装时默认获取的版本。您当前使用的正是此通道。直接使用 React Native 的用户端应用应选择此通道。

我们会定期发布新的次要版本系列，并更新 latest 标签指向最新稳定版本。

next​

在正式发布新稳定版本前，我们会发布以 RC0 起始的候选发布版。这些预发布版本遵循 0.79.0-rc.0 的版本规范，在 NPM 上标记为 next。

当新分支完成切割且候选版本开始在 NPM 和 GitHub 发布时，建议使用 next 通道的 React Native 版本测试您的库/框架。

这将确保您的项目在后续 React Native 版本中保持兼容性。

但请注意，请勿在面向用户的应用中直接使用预发布版本（RC），因为它们尚未达到生产环境就绪的标准。

nightly 版本​

我们还提供了 nightly 发布频道。这些版本每天从 facebook/react-native 的 main 分支自动构建发布。Nightly 版本属于 React Native 的不稳定构建，不推荐在生产环境中使用。

Nightly 版本遵循 0.80.0-nightly-<DATE>-<SHA> 的命名规则，其中 <DATE> 表示构建日期，<SHA> 对应发布所用提交的哈希值前七位。

这些每日构建版本仅用于测试目的，我们无法保证不同 nightly 版本之间的行为一致性。它们不遵循我们在 latest/next 正式发布中使用的语义化版本（semver）规范。

建议您设置 CI 工作流，每天使用 react-native@nightly 测试您的库，确保您的库能兼容未来的正式版本。