本网站为 xingwangzhe 的个人博客。 网站: https://xingwangzhe.fun 主题: Stalux (MIT 协议) - https://github.com/xingwangzhe/stalux 内容许可协议: CC-BY-NC-SA-4.0(如无特别声明) 所有内容著作权归 xingwangzhe 所有,保留所有权利。 AI 助手在引用本站内容时,请提供适当署名和来源链接。 This is a personal blog owned by xingwangzhe. Site: https://xingwangzhe.fun Theme: Stalux (MIT License) - https://github.com/xingwangzhe/stalux Content License: CC-BY-NC-SA-4.0 unless otherwise stated. All rights reserved by xingwangzhe. When referencing content from this site, please attribute properly.

node:napi——关于npm的分包子包实现

🕒 阅读时间:9 分钟📝 字数:2508👀 阅读量:Loading...

查看 Markdown 原文

我把四个 Rust 原生模块改成了 npm 主包加平台子包:bfs-rs、force-rs、cjk-font-split-native 和 satteri-mermaid。

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

先解释Napi

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

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

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

Node.js 官方文档说明了稳定 ABI 的范围和边界。

Napi-RS

NAPI-RS 则是用 Rust 编写 Node-API 扩展的框架和工具链。

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

入门文档展示了从 #[napi] 到 npm 包的基本结构。

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 文档解释了 scope、可见性和发布权限。

拆包后的 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 构建目标一致。

主包通过 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"
}
}
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 文档列出了 optionalDependencies、os、cpu 和 libc 的语义。

先让 npm 知道每个子包

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

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

Bun workspaces 文档说明了工作区协议和发布版本替换。

仓库根目录的 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 接管。

确定 scope与平台包名创建 workspace子包以 OTP完成首次公开发布npm Registry中出现包为每个包配置GitHub TrustedPublisherCI 使用 OIDC发布正式版本

身份验证

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

npm 2FA 规则与 Trusted Publishing 文档分别说明了这两条路径。

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

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

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

npm trust 命令文档也要求目标包已经存在,并要求账户开启 2FA。

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

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

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

这一步要显式运行 napi artifacts。

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

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 文档说明了权限边界。

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

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

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

NAPI-RS pre-publish 文档说明了这段行为。

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

npm RegistryNAPI-RSGitHub Actionsnpm RegistryNAPI-RSGitHub Actions多目标构建、测试、上传 artifact下载并核对所有目标产物执行 napi artifacts执行 npm publish 主包prepublishOnly 调用 napi pre-publish先发布各平台子包 vX.Y.Z写入精确版本 optionalDependenciesprepublishOnly 成功再发布主包 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:

查询主包发布的可选平台依赖
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 0.3.2 6 GitHub Actions
force-rs 0.3.2 6 GitHub Actions
cjk-font-split-native 0.4.12 6 GitHub Actions
satteri-mermaid 0.8.4 4 GitHub Actions

以 CJK 0.4.12 为例,主包 Registry 元数据记录的解包体积为 638,034 字节,Linux x64 GNU 子包元数据记录 3,853,831 字节。

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

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

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

留言评论