---
title: node:napi——关于npm的分包子包实现
tags:
  - Node.js
  - Rust
  - NAPI-RS
  - npm
  - CI
categories:
  - 技术
date: 2026-11-18 17:48:00
desc: 用 NAPI-RS 拆分 Node.js 原生模块的 npm 平台包：从 Node-API 与 napi-rs 的区别、@scope 命名和 bootstrap 占位包，到 OTP、2FA、GitHub OIDC 信任、optionalDependencies 与 CI 发布时序，并记录四个仓库共 22 个平台子包的实际发版结果。
abbrlink: node-napi-npm-platform-packages
---
我把四个 Rust 原生模块改成了 npm 主包加平台子包：`bfs-rs`、`force-rs`、`cjk-font-split-native` 和 `satteri-mermaid`。

最终有 4 个主包、22 个平台包；每个主包通过 `optionalDependencies` 声明平台包，CI 先准备并发布子包，再发布主包,过程及其煎熬，也有可能是Gpt6 Luna实在是太慢太傻了。

<!--more-->

## 先解释Napi

`node:napi` 不是 Node.js 内置模块名。

这里的 NAPI 指 Node-API：Node.js 提供给原生插件使用的一组 C API 和 ABI。

它把插件接口与 V8 的具体版本隔开，使遵守 Node-API 的原生模块能跨多个 Node.js 版本运行；直接依赖 V8、libuv 或其他不稳定接口的代码不自动获得这个保证。

[Node.js 官方文档](https://nodejs.org/download/release/v24.16.0/docs/api/n-api.html)说明了稳定 ABI 的范围和边界。

## Napi-RS


[NAPI-RS](https://napi.rs/) 则是用 Rust 编写 Node-API 扩展的框架和工具链。

Rust 函数通过宏导出为 Node.js 可调用的接口，编译后产生 `.node` 原生二进制、JavaScript 加载入口和类型声明。

[入门文档](https://napi.rs/docs/introduction/getting-started)展示了从 `#[napi]` 到 npm 包的基本结构。

```rust title="NAPI-RS 导出函数的最小示意"
use napi_derive::napi;

#[napi]
pub fn add(left: u32, right: u32) -> u32 {
    left + right
}
```

Node.js 可以稳定调用这层接口，但 `.node` 文件仍要针对操作系统、CPU 架构和 Linux libc 构建。

把所有平台二进制塞进一个 npm 包会让安装体积随支持平台增长；拆分后，主包只携带加载器和类型，匹配当前环境的平台包再提供原生文件。

## 主包和平台包各自负责什么

主包保留对使用者稳定的名字，例如 `@xingwangzhe/cjk-font-split-native`。

平台包把平台信息写进包名，例如 `@xingwangzhe/cjk-font-split-native-linux-x64-gnu`。

scope 是 npm 包名的命名空间；npm 用户名可对应同名 scope，不需要先单独创建一个“空间”。

发布 scoped 包时要设为公开访问，平台包也必须各自作为 Registry 中的包存在。

[npm scopes 文档](https://docs.npmjs.com/about-scopes/)解释了 scope、可见性和发布权限。

```text title="拆包后的 npm 包关系"
@xingwangzhe/cjk-font-split-native
├── JS 加载器与 TypeScript 声明
├── optionalDependencies
│   ├── @xingwangzhe/cjk-font-split-native-darwin-arm64
│   ├── @xingwangzhe/cjk-font-split-native-darwin-x64
│   ├── @xingwangzhe/cjk-font-split-native-win32-x64-msvc
│   ├── @xingwangzhe/cjk-font-split-native-linux-x64-gnu
│   ├── @xingwangzhe/cjk-font-split-native-linux-x64-musl
│   └── @xingwangzhe/cjk-font-split-native-linux-arm64-gnu
└── 当前机器只安装符合 os / cpu / libc 条件的子包
```

子包的 `os`、`cpu` 和 `libc` 字段让包管理器识别适用环境。

下面是简化示例；实际包名和目标三元组需要与 NAPI-RS 配置及 CI 构建目标一致。

```json title="主包通过 optionalDependencies 声明平台子包"
{
  "name": "@xingwangzhe/example-native",
  "version": "1.2.3",
  "optionalDependencies": {
    "@xingwangzhe/example-native-linux-x64-gnu": "1.2.3",
    "@xingwangzhe/example-native-darwin-arm64": "1.2.3"
  }
}
```

```json title="Linux x64 GNU 子包的平台过滤条件"
{
  "name": "@xingwangzhe/example-native-linux-x64-gnu",
  "version": "1.2.3",
  "os": ["linux"],
  "cpu": ["x64"],
  "libc": ["glibc"],
  "files": ["*.node"]
}
```

`optionalDependencies` 表示子包安装失败时，整体安装仍可继续；它不等于所有平台包都会被安装。

npm 默认按平台元数据筛选，但用户用 `--omit=optional` 时会跳过它们。

[npm `package.json` 文档](https://docs.npmjs.com/cli/v11/configuring-npm/package-json/)列出了 `optionalDependencies`、`os`、`cpu` 和 `libc` 的语义。

## 先让 npm 知道每个子包

本地 monorepo 可以用 Bun workspaces 管理根包与 `npm/*` 下的平台包。

开发时子包版本可写成 `workspace:*`；这只是本地工作区关系，发布前要把它们改成实际版本号。

[Bun workspaces 文档](https://bun.sh/docs/pm/workspaces)说明了工作区协议和发布版本替换。

```json title="仓库根目录的 workspace 与发布钩子"
{
  "workspaces": ["npm/*"],
  "scripts": {
    "prepublishOnly": "napi pre-publish --npm-dir npm --tag-style npm --no-gh-release"
  }
}
```

真正麻烦的是首次发布。

GitHub Actions 的 OIDC 信任只能绑定已经存在的 npm 包，而新的平台子包还不存在。

于是每个新子包要先创建并发布一个不含原生二进制的 `0.0.0-bootstrap.0` 占位版本，并挂到 `bootstrap` dist-tag；之后给这个包配置 Trusted Publisher，正式版本才能由 CI 接管。

```mermaid title="平台子包首次启用可信发布"
flowchart 
    A[确定 scope 与平台包名] --> B[创建 workspace 子包]
    B --> C[以 OTP 完成首次公开发布]
    C --> D[npm Registry 中出现包]
    D --> E[为每个包配置 GitHub Trusted Publisher]
    E --> F[CI 使用 OIDC 发布正式版本]
```

## 身份验证

OTP 是 npm 账户 2FA 使用的一次性验证码，用来确认首次发布或信任配置等敏感操作；OIDC 则让符合条件的 GitHub Actions 工作流取得短期发布身份，不必把长期 npm token 放进 CI 密钥。

[npm 2FA 规则](https://docs.npmjs.com/requiring-2fa-for-package-publishing-and-settings-modification/)与 [Trusted Publishing 文档](https://docs.npmjs.com/trusted-publishers/)分别说明了这两条路径。

首次创建包、启用 2FA、录入 OTP、添加可信发布者需要人工授权；此后 CI 发布用 GitHub OIDC。

OTP 只在交互发布时使用，不能写进源码、日志或工作流。

npm 的 trusted publisher 绑定到包与仓库工作流，因此 22 个新子包都要先存在，再逐一设置信任；主包已有的发布配置不能自动覆盖它们。

[`npm trust` 命令文档](https://docs.npmjs.com/cli/v11/commands/npm-trust/)也要求目标包已经存在，并要求账户开启 2FA。

## CI 必须把平台二进制收齐再发布

多平台原生构建通常要在对应 runner 上运行。

CI 为每个目标构建 `.node`，执行目标平台测试，再把产物作为 artifact 上传；发布 job 下载所有 artifact 后，NAPI-RS 把二进制放入对应平台子包目录。

这一步要显式运行 `napi artifacts`。

`napi pre-publish` 只负责准备平台包元数据并发布，不会收集或复制构建产物；如果目标二进制缺失，它可能警告后跳过该平台包，所以发布前必须核对完整目标清单。[NAPI-RS 文档](https://napi.rs/docs/cli/pre-publish)列出了这两个命令的先后关系和缺失产物行为。

```yaml title="GitHub Actions 发布 job 的 OIDC 权限与依赖"
permissions:
  contents: read
  id-token: write

jobs:
  build:
    strategy:
      matrix:
        target: [linux-x64-gnu, linux-x64-musl, darwin-arm64, darwin-x64, win32-x64-msvc, linux-arm64-gnu]
    # 每个目标构建并上传对应 artifact

  publish:
    needs: build
    # 下载所有目标 artifact，检查清单，再执行 npm publish
```

`id-token: write` 只允许该 job 向 GitHub OIDC 服务请求身份令牌；npm 端仍需为每个包配置匹配的 Trusted Publisher。

[GitHub Actions OIDC 文档](https://docs.github.com/en/actions/reference/security/oidc)说明了权限边界。

正式工作流还要校验目标清单，避免某个 artifact 缺失时仍发布一个看起来成功、实际无法加载的主包。

最关键的是发布时间顺序。

NAPI-RS 的 `napi pre-publish` 会把平台包版本对齐到根包版本、补齐主包的 `optionalDependencies`，并逐个发布有产物的平台包；它本身不会发布根包。

[NAPI-RS pre-publish 文档](https://napi.rs/docs/cli/pre-publish)说明了这段行为。

根包的 `prepublishOnly` 钩子完成后，外层 `npm publish` 才会上传主包。

```mermaid title="同一版本的安全发布时序"
sequenceDiagram
    participant G as GitHub Actions
    participant N as NAPI-RS
    participant R as npm Registry
    G->>G: 多目标构建、测试、上传 artifact
    G->>G: 下载并核对所有目标产物
    G->>N: 执行 napi artifacts
    G->>N: 执行 npm publish 主包
    N->>N: prepublishOnly 调用 napi pre-publish
    N->>R: 先发布各平台子包 vX.Y.Z
    N->>N: 写入精确版本 optionalDependencies
    N-->>G: prepublishOnly 成功
    G->>R: 再发布主包 vX.Y.Z
```

如果主包先进入 Registry，而子包版本还不存在，安装器解析主包依赖时就可能遇到 404。

npm 版本发布后不可覆盖；这条流水线也不是事务，子包发布成功一半时不会自动回滚。

失败后应先逐个查询已发布版本，再决定补发或提升新版本，不能盲目重跑同一个版本。

| 顺序 | 发布动作 | 必须成立的条件 |
| --- | --- | --- |
| 1 | 按目标构建并测试原生模块 | Rust target、Node-API 版本和 runner 对应正确 |
| 2 | 汇总并放置构建 artifact | `napi artifacts` 为所有目标准备好二进制 |
| 3 | 发布平台子包 | 子包版本、二进制和平台元数据完整 |
| 4 | 更新主包依赖清单 | `optionalDependencies` 指向刚发布的同版本子包 |
| 5 | 发布主包 | 钩子成功后才将主包写入 Registry |

## npm 页面为什么只显示一个依赖

我在 npm 页面看到主包的 Dependencies 面板只列出普通依赖，例如 `parse5`，没有展示那 6 个平台子包。

页面分组不代表 manifest 中没有可选依赖；应直接查询 Registry 的发布 manifest：

```bash title="查询主包发布的可选平台依赖"
npm view @xingwangzhe/cjk-font-split-native@0.4.12 optionalDependencies --json
```

`npm view` 能查到平台包版本，包自身的 `os`、`cpu`、`libc` 字段能核对筛选条件。

安装时只会选择匹配当前环境的子包，其他系统的二进制不会因为列在同一个依赖对象里就全部落到用户机器上。

## 四个仓库的发布结果

这次四个仓库都使用 `@xingwangzhe/` scope，并由 CI 发布主包和平台子包。

四个主包共关联 22 个平台子包；平台矩阵并不完全相同，Mermaid 包支持 4 个目标，其余三个包各支持 6 个目标。

| 仓库 | 主包版本 | 平台子包 | CI 发布记录 |
| --- | ---: | ---: | --- |
| [`bfs-rs`](https://www.npmjs.com/package/@xingwangzhe/bfs-rs/v/0.3.2) | `0.3.2` | 6 | [GitHub Actions](https://github.com/xingwangzhe/bfs-rs/actions/runs/44253595789) |
| [`force-rs`](https://www.npmjs.com/package/@xingwangzhe/force-rs/v/0.3.2) | `0.3.2` | 6 | [GitHub Actions](https://github.com/xingwangzhe/force-rs/actions/runs/44253612130) |
| [`cjk-font-split-native`](https://www.npmjs.com/package/@xingwangzhe/cjk-font-split-native/v/0.4.12) | `0.4.12` | 6 | [GitHub Actions](https://github.com/xingwangzhe/cjk-font-split-native/actions/runs/44258011497) |
| [`satteri-mermaid`](https://www.npmjs.com/package/@xingwangzhe/satteri-mermaid/v/0.8.4) | `0.8.4` | 4 | [GitHub Actions](https://github.com/xingwangzhe/satteri-mermaid/actions/runs/44261782985) |

以 CJK `0.4.12` 为例，[主包 Registry 元数据](https://registry.npmjs.org/@xingwangzhe%2fcjk-font-split-native/0.4.12)记录的解包体积为 `638,034` 字节，[Linux x64 GNU 子包元数据](https://registry.npmjs.org/@xingwangzhe%2fcjk-font-split-native-linux-x64-gnu/0.4.12)记录 `3,853,831` 字节。

这是 npm 元数据里的 unpacked size，不等同于压缩下载量；真实安装还包括 JS 依赖。

主包不捆绑所有平台 `.node`，也是拆包能控制安装体积的原因。

总之很费心劳神，不过现在体积小了，我准备再次升级我的博客依赖了。


---

**作者：**xingwangzhe

**本文链接：**[https://xingwangzhe.fun/posts/node-napi-npm-platform-packages/](https://xingwangzhe.fun/posts/node-napi-npm-platform-packages/)

本文采用[知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议](https://creativecommons.org/licenses/by-nc-sa/4.0/)进行许可。