用 Rust 写一个 npm 包到底有多简单？从 napi-rs 到发布

导语

前端工程师学 Rust，最常见的场景就是写一个高性能 npm 包。napi-rs 让这个过程变得非常简单：你不需要理解 Rust 的异步运行时，不需要 FFI 胶水代码，只需要写 Rust 函数，napi-rs 帮你生成 Node.js 绑定。

为什么用 Rust 写 npm 包？

JavaScript 是单线程的，CPU 密集型的任务（图像处理、加密、压缩）会阻塞主线程。Rust 编译成原生代码，性能接近 C，但内存安全。一个 Rust 写的图片压缩库，比纯 JS 实现快 10~100 倍。

napi-rs 快速上手

// Cargo.toml
[dependencies]
napi = { version = "2", features = ["napi4"] }
napi-derive = "2"

// lib.rs
use napi_derive::napi;

#[napi]
pub fn fibonacci(n: u32) -> u64 {
  match n {
    0 => 0,
    1 => 1,
    _ => fibonacci(n - 1) + fibonacci(n - 2),
  }
}

两行宏，一个 Node.js 可调用的函数就写好了。

发布流程

1. cargo build --release：编译出原生二进制。
2. napi build：生成 Node.js 可加载的 .node 文件。
3. npm publish：发布到 npm registry。

完整流程不到 10 分钟。

踩过的坑

• 跨平台编译：Windows/macOS/Linux 的原生二进制不通用，CI 里需要跑矩阵编译。
• 类型边界：复杂数据类型（Map、Set、Buffer）在 JS 和 Rust 之间转换需要额外处理。
• 调试困难：Rust 的 panic 会直接 crash Node.js 进程，需要良好的错误处理。

结论

用 napi-rs 写一个简单功能的 npm 包确实很简单，但”能跑”和”能发布”之间还有距离。如果你的 npm 包需要跨平台支持、复杂类型交互、良好的错误处理，建议预留 2~3 天的时间打磨。