如何使用 napi-rs 在 Node.js 中调用 Rust
使用Rust和napi-rs构建Node.js原生插件,导出函数、对象和异步任务,并将各平台预构建二进制文件发布到npm。
要使用 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需要在napicrate 上启用async或tokio_rtfeature,其类型声明为返回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-rs | WebAssembly | node-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 迁移指南进行检查:
| v2 | v3 |
|---|---|
napi.name | napi.binaryName |
napi.triples | 扁平的 napi.targets 数组 |
napi.package.name | napi.packageName |
napi create-npm-dir | napi create-npm-dirs |
JsObject、JsFunction | v3 的类型化 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 字段与当前机器相匹配的那个二进制包。
安装时的具体流程如下:
- 用户安装根包。
- 包管理器跳过
os、cpu或libc字段不匹配的可选包。 - 匹配的平台包安装一个预编译的
.node文件。 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 函数,但也会提高最低版本要求。在所选级别之后新增的函数将无法使用。
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