12k
All articles

如何使用 napi-rs 在 Node.js 中调用 Rust

使用Rust和napi-rs构建Node.js原生插件,导出函数、对象和异步任务,并将各平台预构建二进制文件发布到npm。

OpenReplay Team
OpenReplay Team
如何使用 napi-rs 在 Node.js 中调用 Rust

要使用 napi-rs v3 在 Node.js 中调用 Rust,只需通过 npx @napi-rs/cli new 搭建项目脚手架,用 #[napi] 标注 Rust 函数,执行构建,然后像引入其他模块一样 require 生成的 index.js 即可。

也许是某个哈希循环拖慢了你的事件循环,又或者你需要调用某个原生库,却不想再与 binding.gyp 纠缠。通过 node-gyp 编写 C++ 插件固然可行,但最终每位用户的机器上都得装好 Python 和编译器。本文将从零构建一个可运行的 Rust 插件,为其添加返回对象类型和异步函数,并介绍预编译二进制文件如何通过 npm 分发给用户。

核心要点

  • napi-rs 会将带有 #[napi] 注解的 Rust 代码编译为 .node 二进制文件,同时生成 JavaScript 加载器(index.js)和 TypeScript 类型声明(index.d.ts)。
  • napi-rs v3 项目需要 Rust 1.88+,CLI 还要求 Node.js ^20.17.0、^22.13.0 或 23.5.0+。这一 CLI 版本要求与最终插件所支持的 Node 版本是两回事。
  • 导出的 async fn 需要在 napi crate 上启用 async 或 tokio_rt feature,其类型声明为返回 Promise。
  • napi-rs 包以一个根包加上每个平台各一个可选包的形式发布,因此安装者完全不需要 Rust。

什么是 napi-rs?

napi-rs 是一个用 Rust 构建 Node.js 原生插件的框架。你只需用 #[napi] 标注 Rust 函数,构建过程就会产出一个 .node 二进制文件、一个 JavaScript 加载器,以及根据 Rust 函数签名生成的 TypeScript 类型声明。

napi-rs 构建于 Node-API 之上,后者是 Node 为插件提供的 ABI 稳定的 C 接口。由于接口具备 ABI 稳定性,针对某一 Node-API 级别编译的二进制文件,通常无需重新构建即可在仍提供该级别的后续 Node.js 版本中加载。调用方可以像引入普通模块一样导入插件,并获得带类型的自动补全。

napi-rs 与 WebAssembly:该如何选择?

如果代码运行在服务端,并且需要访问文件系统、使用原生线程或调用现有原生库,请选择 napi-rs;如果同一份代码还需要在浏览器中运行,请选择 Wasm。napi-rs 与 Wasm 并不互斥:napi-rs 可以产出可选的 WASI 构建,生成的加载器也能回退到该构建。

napi-rsWebAssemblynode-gyp C++
文件系统与原生线程支持有限,取决于宿主环境支持
链接现有原生/C 库支持仅当该库被编译为 Wasm 时支持
是否需要按平台构建是,在 CI 中构建否是,或在安装时编译
可选 WASI 构建及加载器回退支持不适用不支持
用户安装时所需的工具链无无通常需要 Python 和 C++ 编译器
自动生成 TS 类型支持取决于工具链不支持

哪种方案更快取决于具体工作负载,请针对你自己的热点路径进行基准测试。如需深入了解 Wasm,可以阅读使用 Wasm 运行高性能代码和为 npm 发布 WebAssembly 包。

创建 napi-rs 项目

要创建 napi-rs 项目,请通过 @napi-rs/cli 包运行 napi new。入门文档列出了前置条件:Rust 1.88 或更高版本、供 CLI 使用的 Node.js ^20.17.0、^22.13.0 或 23.5.0+、Git,以及一个 C 链接器。至于最终插件能在哪些 Node 版本上运行,则是另一个问题,由其编译时所针对的 Node-API 级别决定。

使用 Yarn 模板:

yarn dlx @napi-rs/cli new hash-rs
cd hash-rs
yarn install
yarn build

使用 pnpm 模板:

pnpm dlx @napi-rs/cli new hash-rs --package-manager pnpm
cd hash-rs
pnpm install
pnpm build

目前仅支持 Yarn 和 pnpm 模板。napi new 的交互提示会询问项目路径、包名、Node-API 级别、目标平台、许可证,以及是否生成 CI 工作流。生成的脚手架包含以下文件:

  • src/lib.rs:存放导出的 Rust 函数。
  • Cargo.toml:声明 crate-type = ["cdylib"] 以及 napi-rs v3 相关 crate。请保留其中写入的版本号,并确认其中启用了你所选择的 Node-API 级别 feature。
  • build.rs:自动生成且必不可少。它会调用 napi_build::setup(),必须保留在 crate 根目录下,请勿修改。
  • package.json:其中的 build 脚本会运行 napi build --platform --release。napi 字段块中存放你的配置:
{
  "napi": {
    "binaryName": "hash-rs",
    "targets": ["x86_64-apple-darwin", "aarch64-apple-darwin", "x86_64-unknown-linux-gnu", "x86_64-pc-windows-msvc"]
  }
}

字段值请以你本地生成的文件为准。每次构建都会输出 hash-rs.<platform>.node(例如 hash-rs.darwin-arm64.node),以及 index.js 和 index.d.ts。

为 napi-rs v2 编写的代码无法直接在 v3 中使用。如果你的代码参考自较早的教程,请对照 v2 到 v3 迁移指南进行检查:

v2v3
napi.namenapi.binaryName
napi.triples扁平的 napi.targets 数组
napi.package.namenapi.packageName
napi create-npm-dirnapi create-npm-dirs
JsObject、JsFunctionv3 的类型化 API;旧类型需通过非安全的 compat-mode feature 启用

编写 CPU 密集型 napi-rs 函数

在 pub fn 上添加 #[napi] 即可导出 Rust 函数。首先添加一个哈希 crate:

cargo add sha2

然后将 src/lib.rs 替换为以下 napi-rs v3 代码:

use napi_derive::napi;
use sha2::{Digest, Sha256};

/// Hash `input` with SHA-256, `rounds` times.
#[napi]
pub fn sha256_rounds(input: String, rounds: u32) -> String {
  let mut data = input.into_bytes();
  for _ in 0..rounds.max(1) {
    data = Sha256::digest(&data).to_vec();
  }
  data.iter().map(|b| format!("{:02x}", b)).collect()
}

该函数会将自身的输出重复哈希 rounds 次,这正是那种会阻塞 JavaScript 线程的密集循环。Rust 的 String 映射为 JS 字符串,u32 映射为 JS 数字。十六进制编码采用手动循环实现,因此不依赖 sha2 中与版本相关的格式化方式。使用 yarn build 重新构建后,该函数会以驼峰命名 sha256Rounds 出现在 index.d.ts 中。

在 try.cjs 等 CommonJS 文件中调用它:

const { sha256Rounds } = require('./index.js')
console.log(sha256Rounds('hello', 1))
// 2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824

简单包示例教程采用的也是这种”先构建、再 require”的流程。

返回对象与 Promise

在 napi-rs 中,使用 #[napi(object)] 返回普通 JS 对象,使用 async fn 返回 Promise。根据 Object 概念文档,#[napi(object)] 结构体的每个字段都必须是 pub 的。这样该结构体既可以作为参数,也可以作为返回类型,其值在跨越边界时会被复制。

对于异步函数,需要在 napi 上启用 async feature(或 tokio_rt),并添加 Tokio 以支持文件 I/O:

[dependencies]
# keep the features the scaffold wrote, and append "async"
napi = { version = "3", features = ["async"] }
cargo add tokio --features fs

将以下代码追加到现有的 src/lib.rs 中(该文件已导入 napi 宏和 Sha256)。fs::read 后面的 ? 之所以可用,是因为 napi 会将 std::io::Error 转换为其自身的 Error 类型。

use napi::bindgen_prelude::*;
use tokio::fs;

#[napi(object)]
pub struct FileHash {
  pub path: String,
  pub bytes: u32,
  pub sha256: String,
}

#[napi]
pub async fn hash_file(path: String) -> Result<FileHash> {
  let content = fs::read(&path).await?;
  let sha256: String = Sha256::digest(&content)
    .iter()
    .map(|b| format!("{:02x}", b))
    .collect();
  Ok(FileHash { bytes: content.len() as u32, path, sha256 })
}

导出的 napi-rs async fn 运行在由 napi-rs 管理的 Tokio 运行时上。在生成的类型声明中,hashFile 返回一个 resolve 为 FileHash 对象的 Promise,而 Rust 中的 Err 会变为一个被 reject 的 Promise。async fn 适合此类 I/O 任务;对于耗时较长的纯 CPU 任务,napi-rs 提供了 AsyncTask,可将工作移出主线程执行。

如何将 napi-rs 包发布到 npm?

安装 napi-rs 包的用户无需安装 Rust。napi-rs 包以一个轻量的根包加上每个平台各一个可选包的形式发布,包管理器只会安装 os、cpu 以及(在适用情况下)libc 等 package.json 字段与当前机器相匹配的那个二进制包。

安装时的具体流程如下:

  1. 用户安装根包。
  2. 包管理器跳过 os、cpu 或 libc 字段不匹配的可选包。
  3. 匹配的平台包安装一个预编译的 .node 文件。
  4. index.js 找到该二进制文件并加载它。

napi.targets 列出了你要发布的所有平台。不过,本地执行 napi build 只会编译一个目标,即你的宿主平台(除非传入 --target)。其余二进制文件由生成的 GitHub Actions 工作流负责构建。其发布任务会运行 napi create-npm-dirs,为每个目标创建一个 npm 包目录,然后在发布前将各构建产物移入对应目录。

每个目标都需要独立的包名,因此请使用 npm scope:

{
  "name": "@yourscope/hash-rs",
  "optionalDependencies": {
    "@yourscope/hash-rs-darwin-arm64": "1.0.0",
    "@yourscope/hash-rs-linux-x64-gnu": "1.0.0",
    "@yourscope/hash-rs-win32-x64-msvc": "1.0.0"
  }
}

总结

至此,你已经拥有了一个 Rust 插件:Node 可以像加载其他模块一样加载它,它附带自动生成的类型声明和按平台预编译的二进制文件,用户完全无需安装 Rust 工具链。接下来,不妨把你最慢的 CPU 密集型函数迁移到 src/lib.rs 中,用真实输入将其与 JavaScript 版本进行性能对比,然后推送一个 tag,让生成的 CI 为所有目标平台完成构建。

更多 Rust 相关内容,请参阅 Loco 入门:Rust 版的 Rails。

常见问题

napi-rs 中的 async fn 与 AsyncTask 有什么区别?

async fn 运行在由 napi-rs 管理的 Tokio 运行时上,适用于异步 I/O。AsyncTask 则在 Node 的 libuv 线程池中执行 Task::compute,适用于有限时长的阻塞操作或 CPU 密集型工作。两者都会向 JavaScript 返回 Promise。libuv 线程池与 Node 的文件系统、DNS 和 crypto 操作共享,且 AbortSignal 只能在 AsyncTask 的 compute 步骤开始前将其取消。

如果 Rust 代码在 napi-rs 函数内部发生 panic,会怎样?

若未启用 catch_unwind 选项,传播到 Node-API 边界的 Rust panic 会直接终止整个 Node.js 进程,而不是抛出异常。用 #[napi(catch_unwind)] 标注函数,即可将 panic 转换为由 panic 负载构造的 JavaScript Error。这要求使用默认的 unwind panic 策略,且无法捕获 abort 类型的 panic。对于预期内的失败,应改为返回 Result:同步函数返回的 Err 会作为 JavaScript Error 抛出。

napi-rs 插件能在 Bun 和 Deno 中使用吗?

对 Bun 的支持属于尽力而为。napi-rs 仓库中设有针对最新版 Bun 的 CI 任务,但 Bun 上的失败不会阻塞 napi-rs 的发布,因此请自行在 Bun 中测试你的插件。Deno 原生插件并未纳入 napi-rs 源码的 CI 矩阵,napi-rs 文档也提醒不要仅凭 Node-API 兼容性就假定其支持 Deno。此外,可选的 WASI 回退方案在这两个运行时中也存在已知缺陷。

napi-rs 插件应该针对哪个 Node-API 级别?

Node-API 级别决定了插件可加载的最低运行时版本。针对 Node-API 级别 N 构建的二进制文件,通常可以在仍提供级别 N 的后续 Node.js 版本中加载,无需为每个 Node 主版本重新构建。选择更高的级别可以使用更新的 Node-API 函数,但也会提高最低版本要求。在所选级别之后新增的函数将无法使用。

DevTools for the frontend

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers.

Star on GitHub12k

We use cookies to improve your experience. By using our site, you accept cookies.