napi-rs 的 `napi artifacts` 命令：把 GitHub Actions 编译产物收编进 npm 包并准备发布

开发工具后端【免费下载链接】napi-rsA framework for building compiled Node.js add-ons in Rust via Node-API项目地址https://gitcode.com/gh_mirrors/na/napi-rs点击查看免费下载本文讲解 napi-rs CLI 中napi artifacts命令的完整用法与底层实现。该命令负责把 CIGitHub Actions上跨平台构建产生的.node/.wasm编译产物按照目标平台归档进对应的 npm 子包目录并同步生成浏览器入口、类型声明等配套文件让产物“开箱即可发布”。读完本文你将掌握该命令的全部命令行参数、编程式 API 调用方式以及其目标核对、WASI 特殊处理、原子化文件写入等内部机制。命令定位连接“构建”与“发布”的中间环节在 napi-rs 的项目发布流程中一条典型流水线是先用napi build在 CI 的多个 runner 上分别编译出各平台的二进制然后由napi artifacts把所有 runner 上传的产物汇总到本地最后用napi prepublish兼容旧名napi prePublish或npm publish完成发布。artifacts命令正是负责“汇总与归档”这一步——官方命令描述为Copy artifacts from Github Actions into npm packages and ready to publish即把来自 GitHub Actions 的构建产物复制进 npm 包目录使其处于可发布状态。该命令的定义由代码生成器维护声明于 cli/codegen/commands.ts 中的ARTIFACTS_OPTIONS对应的帮助文档由 cli/codegen 自动生成即本文所依据的 cli/docs/artifacts.md文件头部标注“Do not edit this file manually”而命令的实际行为实现在 cli/src/api/artifacts.ts 的collectArtifacts函数中。用法两种调用方式1. CLI 方式napi artifacts [--options]所有选项均为可选项不带任何参数时使用默认配置即可在标准布局./artifacts输出目录 npm子包目录 根目录package.json下完成归档。2. 编程式 APIimport { NapiCli } from napi-rs/cli new NapiCli().artifacts({ // options })编程式调用的参数接口ArtifactsOptions定义于 cli/src/def/artifacts.ts其applyDefaultArtifactsOptions会在用户未传参时填入默认值见同文件 cli/src/def/artifacts.ts。Options 全表与逐项详解OptionsCLI Optionstyperequireddefaultdescription--help,-hget helpcwd--cwdstringfalseprocess.cwd()The working directory of where napi command will be executed in, all other paths options are relative to this pathconfigPath--config-path,-cstringfalsePath tonapiconfig json filepackageJsonPath--package-json-pathstringfalsepackage.jsonPath topackage.jsonoutputDir--output-dir,-o,-dstringfalse./artifactsPath to the folder where all built.nodefiles put, same as--output-dirof build commandnpmDir--npm-dirstringfalsenpmPath to the folder where the npm packages putbuildOutputDir--build-output-dirstringfalsePath to the build output dir, only needed when targets contain a WASI target--cwd命令的工作目录其余所有路径选项都相对它解析。默认取process.cwd()。它同时参与“包边界”的判定——源码会在cwd与package.json所在目录之间确定一个可管理的文件系统边界防止命令误伤边界外的文件详见 cli/src/utils/misc.ts 的resolvePackageReconciliationPaths。--config-path,-c指向napi配置 JSON 文件的路径。配置中可以声明binaryName、targets、wasm等字段。例如仓库示例 examples/napi/package.json 中即以内嵌napi字段的方式配置了binaryName: example与targets: [wasm32-wasip1, wasm32-wasip1-threads]。若不指定则从packageJsonPath指向的package.json中读取内嵌的napi配置。--package-json-path默认package.json。命令从该文件读取name决定 npm 包名、main决定根入口候选以及内嵌的napi配置。--output-dir,-o,-d默认./artifacts。与napi build的--output-dir保持一致——即 CI 各平台 runner 把编译好的.node/.wasm文件放进的那个目录。命令会递归扫描该目录下的所有.node与.wasm文件自动跳过node_modules见 cli/src/api/artifacts.ts。--npm-dir默认npm。归档产物的目标目录其下会按platformArchABI如linux-x64-gnu、win32-x64-msvc、darwin-arm64、wasm32-wasi建立子目录每个子目录对应一个待发布的平台子包。--build-output-dir仅当targets中包含 WASI 目标时才需要。WASI 构建除了产出.wasm二进制外还会生成 loader 与 worker 等配套 JS 文件这些文件可能并不在--output-dir下而是由构建命令单独输出该参数用于指明它们的所在目录。若未指定命令会回退到在“产物文件所在目录”与cwd中查找见 cli/src/api/artifacts.ts 的候选目录逻辑。底层执行流程一次完整的归档是怎么发生的collectArtifactscli/src/api/artifacts.ts在拿到用户选项后依次执行以下关键步骤路径解析与边界确认通过resolvePackageReconciliationPaths规范化cwd、package.json与npmDir的绝对路径找出“可被命令管理的文件系统边界”防止写入或删除越过包边界。读取配置调用readNapiConfig解析出targets目标三元组列表、binaryName二进制基名、packageName与packageJson。递归收集产物collectNodeBinaries从outputDir递归收集所有.node/.wasm文件并按“产物身份”聚合。产物身份的命名规则在artifactNamecli/src/api/artifacts.ts中定义{binaryName}.{platformArchABI}.{extension}其中 WASI/WASM 平台扩展名为.wasm其余平台为.node。例如binaryName为example时linux x64 gnu 产物即example.linux-x64-gnu.nodeWASI 产物为example.wasm32-wasi.wasm。写入规划所有待写文件先以destination - {content, source}的形式收集进pendingWrites若同一目标被两个不同内容的源文件写入会直接报Conflicting artifacts target错误见addPendingWritecli/src/api/artifacts.ts。根入口处理addArtifactRootEntry会根据package.json的main字段或回退到index.js把 JS 根入口从产物目录复制到包根目录WASI 目标则通过 loader 首行内嵌的元数据WASI_ARTIFACT_METADATA_PREFIX确定托管根入口。原子化提交commitArtifactReconciliation先在系统临时目录创建 staging 区写入全部内容再通过文件系统事务一次性提交cli/src/api/artifacts.ts避免中途失败留下半成品状态。严格的目标核对防止发错包、漏包或重复artifacts命令内置了三层校验全部位于 cli/src/api/artifacts.ts重复身份校验rejectDuplicateArtifactIdentities第 898 行发现同一binaryName.platformArchABI.ext身份对应多个文件时直接报错并提示“确保合并后的 CI 产物中每个配置目标只有一个构建或收窄--output-dir”。这能拦截 CI 合并产物时因路径冲突导致的同目标多份二进制。未配置目标的产物校验若outputDir中存在不属于targets的产物同时也不是 universal 二进制的组成源抛出Artifacts were found for unconfigured targets。防止把某个平台意外构建的二进制一并发布。缺失目标校验若配置的某个目标没有对应产物抛出Missing artifacts for configured targets并同时清理该目标在packageRoot与npmDir下遗留的旧文件removeTargetDestinations避免发布一个“看起来完整但实际缺平台包”的版本。此外命令还会对比“本次将要写入的文件”与npmDir各子包目录、包根目录中已存在的受管文件把不再需要的陈旧文件清理掉collectStaleManagedDestinations第 737 行但outputDir中已存在的普通文件会被收集进protectedSourcePaths保护绝不会被误删第 111-113 行。WASI 目标的特殊处理当targets中包含wasm32-wasi系列目标时归档逻辑远比原生平台复杂loader 文件组每个 WASI flavor 需要一组配套文件由requiredWasiFilescli/src/api/artifacts.ts确定{binaryName}.{suffix}.cjs、{binaryName}.{suffix}.d.cts、{binaryName}.{suffix}-browser.js带线程的 flavor 额外需要wasi-worker.mjs与wasi-worker-browser.mjs非线程 flavor 则换成{binaryName}.{suffix}-deferred.js与-deferred.d.ts。loader 后缀规则wasiLoaderSuffixcli/src/utils/target.ts从platformArchABI去掉wasm32-前缀得到后缀——例如wasm32-wasi得到wasi历史遗留命名wasm32-wasip1得到wasip1因此对应的 loader 文件名分别为example.wasi.cjs与example.wasip1.cjs。源码完整性校验findWasiArtifactSource会在候选目录--build-output-dir→ 产物目录 /cwd中寻找“完整的一组 loader 文件”一旦某个候选目录包含部分文件却又不完整立即报Incomplete artifact source found防止把旧版本地输出与新版 CI 产物混在一起第 353-393 行。浏览器入口重写复制-browser.js时会把其中的new URL(./wasi-worker-browser.mjs, import.meta.url)改写为指向实际发布包名{packageName}-{platformArchABI}/wasi-worker-browser.mjs保证浏览器端 worker 在发布后能正确解析第 254-263 行。这一行为有对应的单元测试验证见 cli/src/api/tests/artifacts.spec.ts测试在临时目录中构造 WASI 产物与buildOutputDir调用collectArtifacts({ cwd, buildOutputDir: build-output })后断言.wasm、loader、worker 及重写后的浏览器入口都正确落入npm/wasm32-wasi/目录。在 CI 中的典型组合用法artifacts通常不与build同机执行构建在各平台 runner 上并行完成并上传产物artifacts在发布机上汇总。一个典型流程是# 1. 在发布机上下载所有平台 runner 上传的产物到 ./artifacts # 2. 汇总归档到 npm/ 目录并核对目标完整性 napi artifacts # 3. 更新各平台子包版本号可选 napi version # 4. 更新 package.json 并准备发布 napi prepublish由于命令默认读取根目录package.json中内嵌的napi配置binaryName、targets无需在命令行重复声明目标列表归档目录结构完全由配置驱动。仓库中的 examples/napi/package.json 与 examples/napi-cargo-test 等示例项目均采用这种配置化布局可作为实际项目的参照。小结napi artifacts是 napi-rs 发布链路中“构建”与“发布”之间的枢纽它以package.json的napi配置为唯一事实来源把散落在./artifacts的跨平台二进制按binaryName.platformArchABI.ext命名规范归档进npm/平台子包同时完成 WASI loader 配套、浏览器入口重写、根入口同步、陈旧文件清理与三层目标完整性校验并以临时目录 staging 文件系统事务的方式原子化落地。理解其参数与内部校验逻辑可以帮助你在 CI 发布流水线中快速定位“缺平台包”“产物重复”“WASI 文件不全”等典型问题。赞分享开发工具后端【免费下载链接】napi-rsA framework for building compiled Node.js add-ons in Rust via Node-API项目地址https://gitcode.com/gh_mirrors/na/napi-rs点击查看免费下载相关推荐MediaPipe快速上手指南5分钟让设备端跑起人脸、手势与姿态检测MediaPipe快速上手指南5分钟让设备端跑起人脸、手势与姿态检测 你的应用需要实时的人脸检测、手势识别或姿态跟踪但又不想自己折腾模型部署MediaPi开发工具后端Mac鼠标优化终极指南让普通鼠标在macOS上获得触控板般流畅体验Mac鼠标优化终极指南让普通鼠标在macOS上获得触控板般流畅体验 还在为Mac上第三方鼠标的糟糕体验而烦恼吗Mac Mouse Fix是一款开源免费的 M桌面应用系统编程3分钟掌握IPTV播放源检查iptv-checker让你的电视直播永不掉线3分钟掌握IPTV播放源检查iptv checker让你的电视直播永不掉线 你是否经常遇到IPTV播放源突然失效需要手动更换频道的困扰iptv check后端任务调度音视频创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考