Daily-It

React Native Nitro 和 TurboModule 总结：新架构中选择原生模块的标准

摘要

React Native Nitro 和 TurboModule 都是为了减少 JavaScript 和本机代码之间的瓶颈而出现的本机模块方法。然而，位置不同。 TurboModule是React Native新架构的官方原生模块系统，Nitro Modules是一个第三方框架，旨在在JSI之上提供更面向对象、更快的原生绑定。在这篇文章中，我们将解释什么是TurboModule和Nitro，在实际项目中应该以什么标准来选择它们，以及在介绍它们时经常卡住的点。

目录

背景

如果你长期使用 React Native，你最终会遇到单独使用 JavaScript 难以处理的领域。代表性示例包括相机帧处理、加密、本地数据库、传感器、BLE、图像/音频处理和特定于平台的 SDK 集成。此时，React Native应用程序必须从JavaScript调用本机API。

过去，Legacy Native Module 通过 JavaScript 和 Native 之间的异步桥来序列化和交换数据。对于一般的应用程序功能来说已经足够了，但对于大型二进制数据或调用非常频繁的本机函数来说，这是一个负担。 React Native 新架构引入了 Fabric、TurboModule、Codegen 和 JSI 等基础来减少这一限制。

截至 2026 年 6 月 18 日，npm react-native 最新版本是 0.86.0React Native官方文档解释了从0.76开始默认如何激活New Architecture。 Nitro 模块的 npm 最新版本是 react-native-nitro-modules@0.35.9确认的。由于这是一个版本变化很快的领域，因此在实际引入之前检查当前项目的 React Native 版本以及所使用的库的要求会更安全。

什么是 TurboModule？

TurboModule 是在 React Native 新架构中创建本机模块的官方方法。主要有以下三个要点。

1. 使用 TypeScript 或 Flow 声明原生模块的接口。 2. React Native Codegen 读取此声明并为 Android/iOS 创建本机接口。 3. 开发人员实现创建的接口，并像类型化 API 一样在 JavaScript 中调用它。

简单来说，TurboModule 是“React Native 核心提供的基于类型的原生模块系统”。官方文档中的一个例子是 NativeLocalStorage 在声明与 TypeScript 规范相同的模块后，Android SharedPreferences, 在 iOS 上 NSUserDefaults它显示了实现流程。

// NativeLocalStorage.ts 예시 형태
import type {TurboModule} from 'react-native';
import {TurboModuleRegistry} from 'react-native';

export interface Spec extends TurboModule {
  getItem(key: string): string | null;
  setItem(value: string, key: string): void;
  removeItem(key: string): void;
  clear(): void;
}

export default TurboModuleRegistry.getEnforcing<Spec>('NativeLocalStorage');

TurboModule的优势在于它的官方支持。因为它是 React Native 核心的一部分，所以它并不强烈依赖于单独的运行时框架。新架构的方向很明确，大多数库兼容性讨论都是在 TurboModule/Fabric 的基础上进行的。

然而，“正式方法”并不意味着“最简单”。当 codegen 设置、Android/iOS 构建设置、是否启用 New Architecture 以及 C++/Objective-C++/Java/Kotlin 的边界交织在一起时，存在初始进入障碍。特别是，那些分发库必须决定是支持以前的旧架构还是仅支持新架构。

什么是Nitro模块？

Nitro Modules 是由 Margelo 的 Marc Rousavy 创建的 React Native 原生模块框架。虽然它不是官方的 React Native 核心功能，但它的目标是提供基于 JSI 的快速且类型安全的本机绑定。

Nitro的核心概念是 Hybrid Object全部。虽然 TurboModule 通常将单个模块公开为单例 API，但 Nitro 强调 JavaScript 中的模型，该模型创建像常规对象一样的本机对象并调用方法和属性。

// Math.nitro.ts 예시 형태
import type {HybridObject} from 'react-native-nitro-modules';

export interface Math extends HybridObject<{ios: 'swift'; android: 'kotlin'}> {
  readonly pi: number;
  add(a: number, b: number): number;
}
import {NitroModules} from 'react-native-nitro-modules';
import type {Math} from './specs/Math.nitro';

const math = NitroModules.createHybridObject<Math>('Math');
const result = math.add(5, 3);

Nitro是 nitrogen它通过名为 的代码生成器从 TypeScript 接口生成 C++、Swift 和 Kotlin 绑定。 iOS 使用 Swift 和 C++ 互操作来减少通过 Objective-C 的次数，Android 支持 Kotlin/Java 和 C++ 互操作。

Nitro 的官方文档解释说，在调用单个本机方法 100,000 次的基准测试中，Nitro 显示出比 TurboModule 更快的结果。不过，这个数字是对“原生方法调用吞吐量”进行极端比较的结果，实际应用性能会因渲染、网络、数据结构、磁盘 I/O、JS 逻辑等其他瓶颈而有所不同。因此，在选择 Nitro 时，您不应该只看基准数据，而应该首先问自己：“我的应用程序真的在本机调用边界出现瓶颈吗？”

TurboModule 与 Nitro

分配 TurboModule Nitro Modules
地点 React Native官方新架构组件 基于JSI的第三方框架
代码生成 React Native Codegen Nitrogen
API模型 面向模块/功能，通常像单例一样使用 以混合对象为中心，强调对象和属性模型
iOS 实现 有许多基于 Objective-C/Objective-C++ 的示例，而 Swift 需要单独考虑桥接。 积极利用 Swift 5.9+ 和 C++ 互操作
安卓实现 Java/Kotlin/C++ 可用 Kotlin/Java/C++ 可用
力量 正规性、生态系统标准、长期兼容性 高性能调用、对象模型、类型安全、Swift/Kotlin 友好设计
注意事项 设置 Codegen 和新架构可能很棘手 需要检查单独的依赖关系、最低要求和快速变化的 API/构建问题

TurboModule符合React Native项目的基本方向。如果你说，“我需要创建一个本机模块，但我想走官方方式”，那么很自然地首先看看 TurboModule。

Nitro 对于性能和对象模型很重要的库来说很有吸引力。例如，Nitro 的混合对象方法可能非常适合“在 JavaScript 端不断携带和操作本机对象”的模型，例如图像对象、帧对象、数据库句柄和音频缓冲区。

评选标准

如果您想在应用程序内轻松调用本机 API，请先查看 TurboModule。

如果您的应用程序仅调用一些平台 API，TurboModule 通常是更安全的默认设置。这是因为React Native官方文档和发行说明中的​​更改是基于TurboModule进行解释的，并且是新架构的一部分。

例如，如果调用频率不高且返回数据简单，例如保存应用设置、简单的设备信息查询或调用内部SDK，TurboModule往往就足够了。

如果您正在构建库并需要高性能对象模型，请考虑 Nitro。

相反，如果库创建者希望将本机对象直接公开给 JavaScript，或者过多的本机调用成为性能瓶颈，那么 Nitro 可能值得考虑。 Nitro 的开发经验对于希望在 Swift/Kotlin 中编写现代本机代码的团队来说可能特别有吸引力。

然而，Nitro 并不是 React Native 的核心功能。因此，构建环境要求、版本兼容性以及团队必须承担的问题响应成本必须一起考虑。

如果您只查看 Expo Managed Workflow，请首先检查库兼容性。

Expo 应用程序中也可能需要本机模块，但在托管工作流中添加本机代码可能受到限制。访问权限取决于是 Expo Dev Client、配置插件还是预构建。如果您想使用基于 Nitro 或 TurboModule 的库，您必须首先检查该库如何支持 Expo 环境。

真正令人困惑的部件和解决方案

情况1. New Architecture已开启，但TurboModule未加载。

症状通常如下所示：

TurboModuleRegistry.getEnforcing(...): 'NativeSomething' could not be found

在本例中，首先是“JavaScript 规范名称”、“本机模块名称”、“Codegen 设置” name/jsSrcsDir”和“包注册”检查它们是否匹配。

{
  "codegenConfig": {
    "name": "NativeLocalStorageSpec",
    "type": "modules",
    "jsSrcsDir": "specs",
    "android": {
      "javaPackageName": "com.nativelocalstorage"
    }
  }
}

这里的常见症结是规范文件位置和模块名称。 TurboModuleRegistry.getEnforcing&lt;Spec&gt;(&#x27;NativeLocalStorage&#x27;)中使用的字符串和本机实现 NAME如果不同，运行时将找不到该模块。在许多情况下，您需要清理构建每个 Android/iOS 才能反映生成的代码。

案例 2.Codegen 不处理 TypeScript 类型

在 React Native GitHub 问题中，仍然存在 Codegen 在处理某些导入类型、复杂联合和 map/null 时的行为与预期不同的情况。并非所有 TypeScript 表达式都会自然转换为本机绑定。

解决这个问题的第一步是简化规范。

// 피하는 편이 안전한 형태: 외부 파일에서 복잡한 타입을 import해서 바로 사용
import type {ExternalComplexType} from './types';

export interface Spec extends TurboModule {
  save(value: ExternalComplexType): void;
}
// 더 안전한 형태: Codegen이 이해하기 쉬운 구조로 spec 경계를 단순화
export type SavePayload = {
  id: string;
  name: string;
  count?: number;
};

export interface Spec extends TurboModule {
  save(value: SavePayload): void;
}

通过在本机边界仅明确定义必要的值而不是按原样传递复杂对象，可以减少构建错误和特定于平台的差异。

案例 3. 安装 Nitro 后 iOS/Android 构建被破坏

Nitro 依赖于最新的 JSI、C++、Swift/Kotlin 和 NDK/Xcode 环境。根据官方文档，Nitro 需要 React Native 0.75 或更高版本，iOS 需要 Xcode 16.4 或更高版本和 Swift 5.9 或更高版本，Android 需要 compileSdkVersion 需要 34 或更高以及 NDK 27 或更高。

首先，请检查以下内容。

node -v
npm view react-native version
npm view react-native-nitro-modules version

在安卓上 compileSdkVersion, ndkVersion，检查 CMake/Gradle 日志，在 iOS 上，您应该在 Xcode Report Navigator 中看到实际失败编译日志中的最后一个错误。仅“构建失败”并不能确定原因。

特别是，查看 Nitro GitHub 问题，会出现本机构建层问题，例如 Swift C++ 互操作、生成的标头冲突和 Android NDK/16KB 页面大小。这个问题仅仅看JavaScript代码是很难解决的。如果满足最低要求后还是收支平衡，可以通过组织所有日志中的实际错误行以及所使用的 React Native/Nitro/Xcode/NDK 版本来快速找到问题。

最佳实践

让原生边界变得小而清晰

无论是 TurboModule 还是 Nitro，JavaScript 和 Native 之间的 API 都应该小而清晰。在native中只传递必要的值而不是传递整个JS对象更有利于调试和类型维护。

首先衡量性能问题

仅仅因为 Nitro 提供快速基准测试并不意味着每个应用程序都应该切换到 Nitro。你首先要衡量到底是原生调用是瓶颈，渲染是瓶颈，还是DB查询是瓶颈。对于调用频率较低的函数，TurboModule 的形式化和可维护性可能是一个更大的优势。

选择库时检查新架构支持状态。

由于React Native 0.76以来新架构的基本激活流程得到了加强，旧的原生库可能会在构建或运行时出现问题。选择库时，您应该检查 README 以了解新架构支持、最新发布日期、未解决的问题和 RN 版本兼容性范围。

FAQ

TurboModule 和 Nitro 可以互相替代吗？

它不是完全相同的技术层。 TurboModule 是 React Native 的官方原生模块系统，而 Nitro 是一个独立的框架，可在 JSI 之上提供更快的、面向对象的绑定。 TurboModule 很适合简单的应用程序内部模块，而 Nitro 可能更适合需要高性能对象模型的库。

即使关闭React Native New Architecture，我还可以使用TurboModule吗？

一般来说，将 TurboModule 与新架构流程一起考虑是正确的。官方文档区分了专用于新架构的 Turbo Native Module 示例和支持旧架构的单独兼容性指南。如果现有的应用程序需要同时支持两者，则必须单独设计兼容层。

如果我使用 Nitro，应用程序总是会更快吗？

不。 Nitro 的优势在于其本机调用边界和对象模型。如果应用程序的瓶颈是渲染、网络、服务器响应、DB 设计或 JS 状态管理，即使引入 Nitro，感知性能也可能不会发生显着变化。

如果我要创建一个新的 React Native 库，我应该选择哪一个？

如果与官方生态系统的长期兼容是您的首要任务，请首先考虑 TurboModule。另一方面，如果它是一个持续处理图像/视频/音频/帧处理等本机对象并且被频繁调用的库，那么 Nitro 是一个值得选择的库。但是，团队必须能够查看 Swift C++ 互操作、Android NDK 和 CMake 日志来处理操作负担。

结论

在React Native中，TurboModule更接近“官方新架构原生模块标准”，Nitro Modules更接近“基于JSI的高性能对象绑定框架”。两者减少桥梁时代限制的方向是一致的，但选择标准不同。

如果您要在应用程序中连接简单的本机 API，那么从 TurboModule 开始会更安全。另一方面，如果你需要在 JavaScript 中长期携带原生对象并频繁调用，或者强烈要求库级别的性能和类型安全，Nitro 值得考虑。重要的是不要仅仅根据技术名称来选择，还要看当前项目的React Native版本、构建环境、团队的原生调试能力以及实际的性能瓶颈。

参考资料

  • React Native 官方文档 – 关于新架构: https://reactnative.dev/docs/the-new-architecture/landing-page
  • React Native 官方文档 – Native Modules：简介: https://reactnative.dev/docs/turbo-native-modules-introduction
  • React Native 博客 – 新架构就在这里: https://reactnative.dev/blog/2024/10/23/the-new-architecture-is-here
  • React Native 0.75 发行说明: https://reactnative.dev/blog/2024/08/12/release-0.75
  • Nitro 官方文档 – 什么是 Nitro？: https://nitro.margelo.com/docs/getting-started/what-is-nitro
  • Nitro 官方文档 – 比较: https://nitro.margelo.com/docs/resources/comparison
  • Nitro 官方文档 – 最低要求: https://nitro.margelo.com/docs/getting-started/minimum-requirements
  • Nitro GitHub 存储库: https://github.com/mrousavy/nitro
  • React Native GitHub 问题搜索 – TurboModule Codegen: https://github.com/react/react-native/issues?q=TurboModule+Codegen
  • 搜索 Nitro GitHub 问题 – build/NDK/Xcode: https://github.com/mrousavy/nitro/issues