napi-rs-test

一个使用 napi-rs 在 Node.js 中调用 Rust 函数的项目。支持多平台发布，根据运行平台自动加载对应的原生模块。

目录

• 环境准备
• 初始化项目
• 构建编译
• 运行测试
• 发布到 npm
• 使用方式
• 项目结构
• 工作原理

环境准备

必需工具

1. Rust (1.70+)

访问 rustup.rs 下载并安装 Rust：

# 验证安装
rustc --version
cargo --version

2. Node.js (18+)

访问 nodejs.org 下载并安装 Node.js：

# 验证安装
node --version
npm --version

3. C++ 构建工具

根据操作系统安装相应的 C++ 构建工具：

Windows:

• 安装 Visual Studio Build Tools 或 Visual Studio Community
• 必须选择 "使用 C++ 的桌面开发" 工作负载

macOS:

xcode-select --install

Linux:

sudo apt-get update
sudo apt-get install build-essential

初始化项目

克隆项目

git clone <repository-url>
cd napi-rs-test

安装依赖

npm install

这会安装以下开发依赖：

• @napi-rs/cli - napi-rs 命令行工具
• vitest - 测试框架
• typescript - TypeScript 编译器
• @types/node - Node.js 类型定义

构建编译

构建当前平台

npm run build

这会：

1. 编译 Rust 代码为当前平台的原生模块（.node 文件）
2. 生成 index.js（JavaScript 绑定文件）
3. 生成 index.d.ts（TypeScript 类型定义文件）

输出文件：

• napi-rs-test.{platform}.node - 原生模块文件
• index.js - JavaScript 绑定
• index.d.ts - TypeScript 类型定义

注意： index.js 是由 napi-rs 自动生成的，不要手动修改，修改会在下次构建时被覆盖。

构建特定平台

要构建特定平台的原生模块，可以使用 napi build 命令：

# 构建特定平台
napi build --target <platform> --release

# 例如：构建 Linux x64
napi build --target x86_64-unknown-linux-gnu --release

注意：

• npm run build 只能构建当前平台
• 构建其他平台需要安装交叉编译工具链：

  # Linux x64
  rustup target add x86_64-unknown-linux-gnu
  rustup target add x86_64-unknown-linux-musl
    
  # macOS 平台无法在 Windows 上直接构建
  # 需要使用 GitHub Actions 或在 macOS 系统上构建

• 推荐使用 GitHub Actions 自动构建所有平台（见下方发布流程）

支持的平台

• win32-x64-msvc - Windows x64
• win32-ia32-msvc - Windows x86
• win32-arm64-msvc - Windows ARM64
• darwin-x64 - macOS x64
• darwin-arm64 - macOS ARM64 (Apple Silicon)
• darwin-universal - macOS Universal Binary
• linux-x64-gnu - Linux x64 (GNU)
• linux-x64-musl - Linux x64 (musl)
• linux-arm64-gnu - Linux ARM64 (GNU)
• linux-arm64-musl - Linux ARM64 (musl)
• linux-arm-gnueabihf - Linux ARM (GNU)
• linux-arm-musleabihf - Linux ARM (musl)
• freebsd-x64 - FreeBSD x64
• android-arm64 - Android ARM64
• android-arm-eabi - Android ARM

运行测试

使用 vitest 运行单元测试：

# 运行测试（监听模式，自动构建）
npm test

注意： 运行测试前会自动执行 npm run build 确保项目已构建。

发布到 npm

本项目使用 GitHub Actions 自动构建并发布所有平台的包。这是最可靠的方式，确保每个平台都在原生环境中构建。

1. 配置 NPM_TOKEN

1. 访问 npmjs.com 并登录
2. 进入账户设置 > Access Tokens
3. 创建新的访问令牌（Access Token），选择 Automation 类型
4. 在 GitHub 仓库中：
   • 进入 Settings > Secrets and variables > Actions
   • 点击 New repository secret
   • 名称：NPM_TOKEN
   • 值：粘贴刚才创建的 npm 访问令牌

2. 更新版本号并推送

# 更新 package.json 中的版本号
npm version patch  # 或 minor, major

# 推送代码到主分支
git push

注意： 不需要手动创建和推送标签，GitHub Actions 会在发布成功后自动创建并推送版本标签。

3. 自动发布流程

GitHub Actions 会自动执行以下步骤：

1. 检查版本：检查 npm 上是否已存在该版本
2. 构建并发布平台包：如果版本不存在，并行构建并发布多个平台的包
   • win32-x64-msvc - Windows x64（在 windows-latest runner 上构建）
   • darwin-universal - macOS Universal Binary（在 macos-latest runner 上构建）
   • linux-x64-gnu - Linux x64（在 ubuntu-latest runner 上构建）
3. 发布主包：所有平台包发布完成后，发布主包
4. 创建版本标签：发布成功后，自动创建并推送版本标签（v{version}）
5. 创建 GitHub Release：自动在 GitHub 上创建 Release，包含更新内容和安装说明

工作流特性

• 自动触发：推送到主分支（main 或 master）时自动触发
• 手动触发：支持在 GitHub Actions 页面手动触发（workflow_dispatch）
• 版本检查：自动检查版本是否存在，避免重复发布
• 多平台并行构建：使用 matrix strategy 并行构建多个平台，提高效率
• 原生构建：每个平台在对应的原生环境中构建，无需交叉编译
• 容错机制：一个平台失败不影响其他平台的构建（fail-fast: false）
• 自动标签：发布成功后自动创建并推送版本标签
• 自动 Release：发布成功后自动在 GitHub 上创建 Release，包含更新内容和安装说明

注意：当前支持 Windows x64、macOS Universal 和 Linux x64 平台的发布。更多平台支持可以根据需要添加。

工作流文件

发布工作流配置文件位于 .github/workflows/publish.yml。

使用方式

安装

npm install napi-rs-test

安装时会自动检测当前平台并安装对应的平台包（如 napi-rs-test-win32-x64-msvc、napi-rs-test-darwin-universal 等）。

注意：

• 如果本地存在 .node 文件（开发环境），会自动跳过平台包安装
• 如果平台包未发布或安装失败，会显示警告但不影响主包安装
• 可以手动安装平台包：npm install napi-rs-test-{platform}

TypeScript / ES Modules

import { sum, fibonacci, greet, Calculator } from 'napi-rs-test';

// 基本函数
console.log(sum(10, 20)); // 30
console.log(fibonacci(10)); // 55n (bigint)
console.log(greet('World')); // "Hello, World! Welcome to napi-rs!"

// 类使用
const calc = new Calculator(10);
calc.add(5);        // 15
calc.subtract(3);  // 12
calc.multiply(2);  // 24
console.log(calc.getValue()); // 24

CommonJS

const { sum, fibonacci, greet, Calculator } = require('napi-rs-test');

// 使用方式同上
console.log(sum(10, 20)); // 30

API 文档

sum(a: number, b: number): number

计算两个数字的和。

sum(5, 3); // 8

fibonacci(n: number): bigint

计算第 n 个斐波那契数。

fibonacci(10); // 55n
fibonacci(0);  // 0n
fibonacci(1);  // 1n

greet(name: string): string

生成问候语。

greet('World'); // "Hello, World! Welcome to napi-rs!"

Calculator

计算器类。

const calc = new Calculator(initialValue: number);

// 方法
calc.add(value: number): number      // 加法，返回当前值
calc.subtract(value: number): number // 减法，返回当前值
calc.multiply(value: number): number // 乘法，返回当前值
calc.getValue(): number              // 获取当前值

项目结构

napi-rs-test/
├── src/                     # Rust 源代码目录
│   └── lib.rs              # Rust 源代码
├── test/                    # 单元测试目录
│   └── index.test.ts       # 测试文件
├── scripts/                 # 脚本目录
│   ├── publish-platform.js # 发布单个平台
│   └── install-platform.js # 自动安装平台包脚本
├── .github/
│   └── workflows/
│       └── publish.yml     # GitHub Actions 发布工作流
├── Cargo.toml              # Rust 项目配置
├── build.rs                # Rust 构建脚本
├── .gitignore              # Git 忽略文件
├── index.js                # napi-rs 生成的 JavaScript 绑定（包含平台检测逻辑）
├── index.d.ts              # TypeScript 类型定义
├── *.node                  # 编译后的原生模块文件
├── package.json            # 主包配置（包含 napi 配置）
├── tsconfig.json           # TypeScript 配置
└── vitest.config.ts        # Vitest 测试配置

工作原理

多平台支持机制

1. 主包 (napi-rs-test)：

   • 包含平台检测逻辑（index.js）
   • 包含 TypeScript 类型定义（index.d.ts）
   • 不包含原生模块文件

2. 平台包 (napi-rs-test-{platform})：

   • 每个平台有独立的 npm 包
   • 包含特定平台的原生模块（.node 文件）
   • 例如：napi-rs-test-win32-x64-msvc、napi-rs-test-darwin-universal

3. 自动安装：

   • 安装主包时，postinstall 脚本会自动检测平台并安装对应的平台包
   • 如果本地存在 .node 文件（开发环境），会跳过自动安装
   • macOS 会优先尝试安装 darwin-universal，失败则回退到特定架构包

4. 运行时加载：

   • 首先尝试加载本地 .node 文件（开发环境）
   • 如果不存在，则尝试加载对应平台的 npm 包（生产环境）
   • 自动根据 process.platform 和 process.arch 选择正确的平台包

构建流程

1. Rust 编译：cargo build --release 编译 Rust 代码为原生模块
2. 生成绑定：napi-rs 生成 index.js 和 index.d.ts
3. 平台检测：index.js 包含平台检测逻辑，自动加载对应的 .node 文件

许可证

MIT