开发工具后端【免费下载链接】napi-rsA framework for building compiled Node.js add-ons in Rust via Node-API项目地址https://gitcode.com/gh_mirrors/na/napi-rs点击查看免费下载napi create-npm-dirs是 napi-rs CLInapi-rs/cli中负责为不同编译目标平台生成 npm 包目录的核心命令。它读取项目根package.json中的napi配置与 Cargo 编译产物清单在npm/目录下为每个平台产出带平台后缀的 scoped 包如linux-x64-gnu、darwin-arm64、wasm32-wasi并自动补齐这些平台包发布所需的package.json、README 与类型声明。读完本文你将掌握该命令的全部 CLI 与程序化调用方式、每个配置项的语义与默认值、平台包目录的生成规则以及 WASI 目标包被自动注入运行时依赖和 Node 引擎约束的底层原理。本文对应的官方命令文档位于 cli/docs/create-npm-dirs.md该文档由 cli/codegen/index.ts 自动生成不建议手工编辑命令的完整命令列表可参见 cli/README.md。命令定位发布流水线中的骨架生成器在 napi-rs 的发布流程中create-npm-dirs承担的是目录骨架与元数据生成环节。它的上游是napi build产出各平台的.node二进制或.wasm产物下游则通常与另外三个命令配合使用napi artifacts把 CI如 GitHub Actions构建出的产物拷贝到各平台包目录中文档见 cli/docs/artifacts.mdnapi version统一更新由create-npm-dirs生成的各平台包中的版本号文档见 cli/docs/version.mdnapi pre-publish发布前校验并更新package.json、拷贝 addon 到各平台包文档见 cli/docs/pre-publish.md。一条典型的流水线是napi build多平台交叉编译→napi create-npm-dirs生成平台包目录与元数据→napi artifacts把 CI 产物放入平台包→napi version/napi pre-publish同步版本并发布。create-npm-dirs生成的每个平台目录都是一个独立、可直接npm publish的最小 npm 包。两种调用方式1. CLI 方式napi create-npm-dirs [--options]例如napi create-npm-dirs --npm-dir npm --dry-run2. 程序化方式CLI 同样暴露了对应的 TypeScript API便于在自定义构建脚本或测试中调用import { NapiCli } from napi-rs/cli new NapiCli().createNpmDirs({ // options cwd: process.cwd(), npmDir: npm, dryRun: false, })程序化入口对应的底层实现位于 cli/src/api/create-npm-dirs.ts 的createNpmDirs(userOptions)函数而 CLI 命令类clipanion 实现定义在 cli/src/commands/create-npm-dirs.ts选项声明在 cli/src/def/create-npm-dirs.ts。选项参数详解下表完整继承自原文档并补充了源码层面的默认值与行为说明OptionsCLI Optionstyperequireddefaultdescription--help,-h获取帮助cwd--cwdstringfalseprocess.cwd()napi命令执行的工作目录其余所有路径选项均相对于此路径configPath--config-path,-cstringfalsenapi配置文件JSON的路径packageJsonPath--package-json-pathstringfalsepackage.jsonpackage.json的路径npmDir--npm-dirstringfalsenpm存放各平台 npm 包的根目录dryRun--dry-runbooleanfalsefalse试运行模式不触碰文件系统cwd所有其他相对路径configPath、packageJsonPath、npmDir都会以它为基准解析。默认值为process.cwd()。在程序化调用中建议显式传入项目根目录避免进程工作目录与项目目录不一致导致解析错误。configPath与packageJsonPath这两个选项共同决定配置来源。packageJsonPath指向根package.json默认package.jsonconfigPath指向可选的独立napi配置文件。从源码看配置读取逻辑cli/src/utils/config.ts 的readNapiConfig支持两种形态若不传configPath直接读取packageJsonPath中的package.json其napi字段作为配置若传configPath读取独立 JSON 配置文件如napi.jsonpackage.json仍作为包元数据来源。napi配置的关键字段包括binaryName生成的.node/.wasm二进制文件名旧字段name已弃用targets编译目标三元组列表例如x86_64-unknown-linux-gnu、aarch64-apple-darwin、wasm32-wasip1-threadswasmWASM 相关配置其中wasm.asyncRuntimeboolean控制是否启用异步运行时、wasm.browser.fs/wasm.browser.bufferboolean控制浏览器端的 polyfill 依赖注入。一个真实的配置示例可见 examples/napi/package.json其napi字段同时配置了wasm32-wasip1与wasm32-wasip1-threads两个 WASI 目标。注意targets中不允许出现重复或等价拼写config.ts会按parseTriple解析出的platformArchABI做去重校验重复目标会直接抛错。npmDir各平台包目录的父目录默认npm。解析逻辑cli/src/api/create-npm-dirs.ts 的resolveManagedPackageDirectories会把npmDir解析为cwd下的绝对路径然后在其下创建每个目标的子目录。dryRun试运行模式。开启后命令会完整执行配置读取、目标解析、文件内容规划与日志输出但不会写入任何文件源码中options.dryRun为真时直接return跳过publishPackageMetadata的文件系统事务。典型用途是在发布前检查将要生成的平台包结构与内容。目录生成规则平台目录如何命名对于配置中的每个 targetcreate-npm-dirs会按target.platformArchABI生成一个目录名并创建形如npm/platformArchABI/的包目录。例如x86_64-unknown-linux-gnu→npm/linux-x64-gnu/aarch64-apple-darwin→npm/darwin-arm64/x86_64-pc-windows-msvc→npm/win32-x64-msvc/wasm32-wasip1-threads→npm/wasm32-wasi/wasm32-wasip1→npm/wasm32-wasip1/值得注意的是 WASI 目标的目录名映射源码中的MANAGED_WASI_PACKAGE_TARGETS常量wasm32-wasi目录对应wasm32-wasip1-threads目标线程版wasm32-wasip1目录对应wasm32-wasip1目标无线程版。每个平台包内部会生成三类内容package.json平台化后的包清单详见下文README.md自动生成的平台包说明内容为This is the **triple** binary for packageName源码readme()函数仅 WASI.d.ts类型声明如example.wasm32-wasip1.wasm.d.ts内容由createWasmModuleTypeDef()生成。同时命令还会清理过期的 WASI 包目录若targets中不再包含某个 WASI 目标对应目录中此前由命令托管生成的文件如.wasm、loader、package.json、托管 README会被自动移除空目录一并删除collectStaleWasiPackageRemovals/removeEmptyStalePackageDirectories保证平台包目录与配置始终一致。平台包package.json的生成细节原生.node目标对非 wasm32 目标生成的 scoped 包package.json结构如下源码createNpmDirsUnlocked中的scopedPackageJson{ name: packageName-linux-x64-gnu, version: 根 package.json 的 version, cpu: [x64], os: [linux], libc: [glibc], main: binaryName.linux-x64-gnu.node, files: [binaryName.linux-x64-gnu.node] }关键字段的生成规则包名packageName-platformArchABI即根包名加平台后缀保证 npm 上各平台包互不冲突version直接继承根package.json的version字段cpu/os从 target 的架构与平台推导。当 target 为universal或wasm32时cpu会被省略libcabi为gnu时写[glibc]为musl时写[musl]帮助 npm 在 glibc/musl 发行版之间正确选择main/files指向平台二进制binaryName.platformArchABI.nodefiles仅包含该二进制继承字段通过pick()从根包继承description、keywords、author、authors、homepage、license、engines、repository、bugs等元数据publishConfig若根包存在仅透传registry与access两个键其余如exports、tag一律丢弃——测试 cli/src/api/tests/create-npm-dirs.spec.ts 中的should omit exports fields from publishConfig用例验证了这一点。cpu、os、libc的组合让 npm 能将平台包作为optionalDependencies时只在匹配的平台上安装从而实现一个包名、按平台自动拉取对应二进制的经典发布模式。WASI.wasm目标WASI 包的package.json结构差异较大源码同样位于 cli/src/api/create-npm-dirs.ts。以wasm32-wasip1-threads为例生成内容大致如下{ name: packageName-wasm32-wasi, version: 根包版本, type: module, main: binaryName.wasm32-wasi.cjs, types: binaryName.wasm32-wasi.d.cts, browser: binaryName.wasm32-wasi-browser.js, files: [ binaryName.wasm32-wasi.wasm, binaryName.wasm32-wasi.cjs, binaryName.wasm32-wasi.d.cts, binaryName.wasm32-wasi-browser.js, wasi-worker.mjs, wasi-worker-browser.mjs ], engines: { node: ^20.19.0 || ^22.13.0 || 23.5.0 }, dependencies: { napi-rs/wasm-runtime: ~latest, emnapi/core: emnapi 当前版本, emnapi/runtime: emnapi 当前版本 } }几个值得注意的实现细节不写cpu/osWASI 模块运行在普通宿主进程内Node/浏览器/workerd源码注释明确说明给 WASI 包标记cpuwasm32会让 npm 在 x64/arm64 宿主上拒绝直接安装并在其为 optionalDependency 时静默跳过——因此这里刻意省略cpu、os字段入口换为 loadermain指向 CJS loader.cjsbrowser指向浏览器 loader并配套types.d.cts线程版 vs 无线程版线程版wasm32-wasip1-threads目录wasm32-wasi额外包含wasi-worker.mjs、wasi-worker-browser.mjs无线程版wasm32-wasip1则生成-deferred.js/-deferred.d.ts、.wasm.d.ts并导出exports映射.、./workerd、./wasm、./wasm.wasm、./package.json五个子路径其中./workerd指向 workerd 安全的 deferred loader运行时依赖自动注入命令会实时访问 npm registry 解析napi-rs/wasm-runtime的latestdist-tag默认 registry 为https://registry.npmjs.org/可通过npm_config_registry环境变量覆盖测试用例专门验证了这一点并以波浪号范围~latest写入依赖——注释说明这是为了让生成的包停留在已解析的 minor 版本上、同时允许修复性升级。emnapi/core与emnapi/runtime则直接锁定为 CLI 本地安装的emnapi版本require(emnapi/package.json).version当napi.wasm.asyncRuntime true时还会追加napi-rs/async-runtime: ^latest浏览器 buffer polyfill当wasm.browser.buffer true且wasm.browser.fs ! true或目标为无线程 WASI时注入buffer: ^6.0.3源码常量directBufferDependencyengines.node约束WASI 包会强制 Node 版本下限。源码 cli/src/utils/version.ts 定义了MINIMUM_WASI_NODE_VERSION ^20.19.0 || ^22.13.0 || 23.5.0restrictWasiNodeEngine()会把根包的engines.node与该下限求交集更严格的范围保留、更宽的范围收窄、不满足下限的精确版本直接抛错。相关用例如24保留、18被提升到下限、13.0.0抛错可在 cli/src/api/tests/create-npm-dirs.spec.ts 中看到。底层机制文件系统安全与事务化提交create-npm-dirs并非简单地把文件写进磁盘它有两层保障机制路径安全校验assertSafeManagedPathSegment校验binaryName与平台目录名必须为单一路径段拒绝空串、.、..、含/或\、绝对路径等assertSafeTargetDirectory拒绝把符号链接或 junction 当作 npm 目标目录防止目录穿越类风险。事务化文件写入非dryRun时整个写入过程通过withFileSystemReconciliation(boundary, ...)与commitFileSystemTransaction包裹见 cli/src/utils/index.ts 导出的工具。所有待写内容先暂存到临时目录mkdtemp前缀napi-rs-create-npm-dirs-stage-随后与待删除的过期文件一起以事务方式提交boundary由resolvePackageReconciliationPaths计算用于约束文件系统操作范围。这样即使中途失败也不会留下半成品平台包。此外命令在解析依赖版本时会联网请求 npm registry 元数据若网络不通或响应异常如缺少latestdist-tag会抛出带明确提示的错误信息getLatestPackageVersion函数。调试与常见用法CLI 内置 debug 日志排查问题时可用DEBUGnapi:* napi create-npm-dirs日志中包含平台目录规划Plan npm package dir、待写文件Writing file、过期文件移除Removing stale managed file等信息在--dry-run模式下待写文件内容会直接输出到 debug 日志方便先行核对。发布前建议按以下顺序自查根package.json的napi.targets是否覆盖全部目标平台含 WASI运行napi create-npm-dirs --dry-run检查将生成的平台目录与元数据确认网络可达WASI 目标需要解析运行时依赖版本正式执行napi create-npm-dirs后再跑napi artifacts填充二进制产物。小结napi create-npm-dirs用一条命令把多平台发布中最繁琐的元数据编排自动化它从单一根配置推导出全套平台包目录为原生目标写入cpu/os/libc过滤字段为 WASI 目标注入运行时依赖、Node 引擎约束与多入口 loader并通过路径安全校验与事务化提交保证产物的一致性。其实现完整地落在 cli/src/api/create-npm-dirs.ts 中配套的 20 余个测试用例cli/src/api/tests/create-npm-dirs.spec.ts覆盖了 publishConfig 过滤、WASI 依赖解析、engines 约束、registry 环境变量等关键行为可作为理解该命令细节的一手参考资料。赞分享开发工具后端【免费下载链接】napi-rsA framework for building compiled Node.js add-ons in Rust via Node-API项目地址https://gitcode.com/gh_mirrors/na/napi-rs点击查看免费下载相关推荐Mac鼠标优化终极指南让普通鼠标在macOS上获得触控板般流畅体验Mac鼠标优化终极指南让普通鼠标在macOS上获得触控板般流畅体验 还在为Mac上第三方鼠标的糟糕体验而烦恼吗Mac Mouse Fix是一款开源免费的 M桌面应用系统编程npm trust 命令全解基于 OIDC 为 npm 包配置 CI/CD 可信发布者npm trust 命令全解基于 OIDC 为 npm 包配置 CI/CD 可信发布者 npm trust 是 npm CLI 中用于在 npm 包与 CI/开发工具包管理器CLInpm npx 完全指南从本地或远程 npm 包运行命令npm npx 完全指南从本地或远程 npm 包运行命令 导读 npx 是 npm 官方提供的命令执行器它允许你在不修改项目依赖的前提下直接运行一个 np开发工具包管理器CLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考