开发工具后端【免费下载链接】napi-rsA framework for building compiled Node.js add-ons in Rust via Node-API项目地址https://gitcode.com/gh_mirrors/na/napi-rs点击查看免费下载napi build是 napi-rs 项目 napi-rs/cli 的核心构建命令负责将 Rust crate 编译为 Node-API 原生模块.node并自动生成 JS binding 加载器与 TypeScript 类型定义.d.ts。本文以 cli/docs/build.md 为骨架结合 构建管线源码、命令定义 与仓库内真实项目配置系统讲解该命令的完整选项、napi 配置文件的读写规则、跨平台编译三套机制及底层执行链路帮助你从能跑通进阶到可复现、可定制、可发布。命令总览两种调用方式CLI 方式在终端中执行napi build [--options]编程方式Programmatic API在 Node.js/TypeScript 项目中导入napi-rs/cliimport { NapiCli } from napi-rs/cli new NapiCli().build({ // options })NapiCli类的定义位于 cli/src/index.ts它暴露了build、new、createNpmDirs、prePublish、rename、universalize、artifacts、version等全部 API其中build buildProject即 CLI 命令与编程接口走的是同一条 构建管线。说明cli/docs/build.md文件头部标注This file is generated by cli/codegen. Do not edit this file manually即文档由 codegen 工具 从 def/build.ts 的命令定义自动生成两者内容一一对应可作为交叉验证依据。选项完全解析下表完整继承自 cli/docs/build.md 的选项矩阵随后按功能分组深入讲解。选项编程 APICLI 选项类型必填默认值说明--help,-h查看帮助target--target,-tstring否为目标三元组构建透传给cargo build --targetcwd--cwdstring否napi命令执行的工作目录其余路径选项都相对于此路径manifestPath--manifest-pathstring否指向Cargo.toml的路径configPath--config-path,-cstring否指向napi配置文件JSON的路径packageJsonPath--package-json-pathstring否指向package.json的路径targetDir--target-dirstring否所有 crate 构建产物的目录同cargo build --target-diroutputDir--output-dir,-ostring否所有构建文件输出目录默认为 crate 所在目录platform--platformboolean否给生成的 Node.js binding 文件名加上平台三元组如[name].linux-x64-gnu.nodejsPackageName--js-package-namestring否生成的 JS binding 文件中的包名仅在--platform下生效constEnum--const-enumboolean否是否为 TypeScript binding 生成 const enumruntimeStringEnum--runtime-string-enumboolean否在--no-const-enum下将#[napi(string_enum)]枚举生成为运行时枚举export declare enum默认是纯类型 unionjsBinding--js,--js-bindingstring否生成的 JS binding 文件路径与文件名仅在--platform下生效相对--output-dirnoJsBinding--no-jsboolean否是否禁用 JS binding 文件生成仅在--platform下生效dts--dtsstring否生成的类型定义文件路径与文件名相对--output-dirdtsHeader--dts-headerstring否自定义类型定义文件头仅在启用typedeffeature 时生效noDtsHeader--no-dts-headerboolean否是否禁用生成的类型定义文件默认文件头仅在启用typedeffeature 时生效dtsCache--dts-cacheboolean否true是否启用 dts 缓存默认为 trueformat--formatesm \| commonjs否生成的 JS binding 文件的模块格式仅在--platform下生效默认commonjsesm--esmboolean否--format esm的别名commonjs--commonjsboolean否--format commonjs的别名strip--strip,-sboolean否是否 strip 库以获得最小文件体积release--release,-rboolean否以 release 模式构建verbose--verbose,-vboolean否详细输出构建命令追踪日志bin--binstring否仅构建指定的 binarypackage--package,-pstring否构建指定库或 cwd 下的库profile--profilestring否以指定 profile 构建产物crossCompile--cross-compile,-xboolean否[实验性] 通过替换 cargo 子命令实现交叉编译详见下文三套交叉编译机制首次使用自动安装所选子命令不能与--use-cross、--use-napi-cross、--watch组合useCross--use-crossboolean否[实验性] 不推荐优先使用--cross-compile或--use-napi-cross在 Docker 或 Podman 容器中使用cross构建需手动安装且需要运行中的容器引擎不能与--cross-compile、--use-napi-cross、--watch组合useNapiCross--use-napi-crossboolean否[实验性] 从napi-rs/cross-toolchain下载预编译 gcc 交叉工具链glibc 2.17并设置 linker 与 C 编译器环境变量仅支持 Linux glibc 目标x64、arm64、armv7、ppc64le、s390x且仅在 Linux x64 或 arm64 宿主机上其他目标或宿主机会报错不能与--cross-compile、--use-cross组合watch--watch,-wboolean否监听 crate 变化并借助cargo-watch持续构建features--features,-Fstring[]否以空格分隔的 feature 列表allFeatures--all-featuresboolean否激活所有可用 featurenoDefaultFeatures--no-default-featuresboolean否不激活defaultfeatureohosSign--ohos-signboolean否true是否为 OpenHarmony 目标构建的二进制注入.codesignfs-verity 段进行自签名使.so能在 HarmonyOS 设备上加载仅对*-unknown-linux-ohos目标生效路径与工程定位选项cwd是所有相对路径的基准manifest-path、config-path、package-json-path、target-dir、output-dir分别定位 Cargo 清单、napi 配置、npm 清单、构建产物与最终输出位置。默认output-dir为 crate 所在目录即构建产物会落在cargo build的目标目录中经拷贝而来。这些选项在 def/build.ts 中逐个声明并通过getOptions()汇总命令层执行时再与cargoOptionsRest 参数合并最终调用buildProject见 commands/build.ts。产物生成与命名选项--platform是发布多平台 npm 包的关键开关开启后生成的 binding 文件会带上目标三元组后缀。底层命名规则在 createArtifactDestinationName 中实现if (platform || target.platform wasi) { destinationName .${target.platformArchABI} } return ${destinationName}.${sourceName.endsWith(.wasm) ? wasm : node}即最终产物形如[binaryName].linux-x64-gnu.node、[binaryName].wasm32-wasip1.wasm。注意WASI 目标即使不传--platform也会自动加平台后缀。--js-binding别名--js与--dts控制 JS 加载器与类型定义文件的文件名与位置相对--output-dir--no-js完全禁用 JS binding 生成--format esm|commonjs默认commonjs另有--esm/--commonjs别名决定加载器的模块格式源码中有专门的测试用例验证format 显式指定时不受文件名后缀影响见 build.spec.ts--const-enum控制 TS 绑定中是否生成 const enum--runtime-string-enum则用于将#[napi(string_enum)]枚举在非 const enum 模式下输出为运行时枚举--dts-header/--no-dts-header控制类型定义文件头需napi-derive开启typedeffeature--dts-cache默认开启配合下文dts 缓存小节使用。构建模式选项--release-r与--strip-s分别对应 release 编译与产物瘦身--profile走 cargo 的 profile 机制--bin/--package限定构建对象--features/--all-features/--no-default-features控制 feature 组合--verbose输出构建命令追踪。仓库根 package.json 中典型用法为build: napi build --release, build:debug: napi build三套交叉编译机制文档明确标注三者均为实验性能力且互斥--cross-compile推荐首选通过替换 cargo 子命令实现——从非 Windows 宿主机构建 Windows MSVC 目标时使用cargo-xwinwindows-gnu目标会被拒绝因为cargo-xwin无法处理非 Windows 目标使用cargo-zigbuild要求zig在 PATH 中。所选子命令会在首次使用时自动安装。不能与--use-cross、--use-napi-cross、--watch组合。--use-cross不推荐在 Docker 或 Podman 容器中用cross构建需手动安装且要有运行中的容器引擎。--use-napi-cross自动从napi-rs/cross-toolchain下载预编译 gcc 交叉工具链glibc 2.17并设置 linker 与 C 编译器环境变量仅限 Linux glibc 目标x64、arm64、armv7、ppc64le、s390x且宿主必须是 Linux x64 或 arm64其余情况直接报错。源码中还有专门的validateCrossCompileFlags校验测试用例 build.spec.ts 验证了同时组合两种交叉编译机制会抛错、单一机制被允许、--cross-compile拒绝windows-gnu目标三个行为。监听模式--watch-w借助cargo-watchcrate 监听 crate 变化并持续构建适合开发期热迭代。OpenHarmony 签名--ohos-sign默认为true对*-unknown-linux-ohos目标构建后会向二进制注入.codesignfs-verity 段完成自签名使其能在 HarmonyOS 设备上被加载。相关实现与测试见 ohos-selfsign.ts 及 ohos-selfsign.spec.ts。由于默认开启若不需要该行为应显式传入--no-ohos-sign。该默认值同样体现在applyDefaultBuildOptionsdef/build.ts中——dtsCache: true与ohosSign: true是仅有的两个带默认值的选项。文档未列出但源码存在的附加能力从 commands/build.ts 可以看到实际的napi build命令还支持两个文档表格之外的参数--pipe 命令将每个输出文件路径通过管道传给指定命令例如napi build --pipe npx oxfmt典型用于格式化生成的 JS/类型文件尾部 Rest 参数cargoOptions透传给底层cargo build的额外参数。napi 配置package.json的napi字段与独立配置文件除了命令行参数napi build还会读取项目配置。读取逻辑集中在 readNapiConfig配置来源有两处package.json的napi字段或--config-path指定的独立 JSON 文件若两者同时存在会打印警告并以独立配置文件为准Object.assign(userNapiConfig, separatedConfig)解析失败JSON 语法错误会直接抛错默认值binaryName为index、packageName取package.json的name、npmClient为npm、targets为空数组兼容旧配置napi.name已废弃改用binaryNamenapi.triples.defaults/additional已废弃改用targets命中时会打印[DEPRECATED]警告目标校验重复 target 会报Duplicate targets are not allowed不同拼写但解析后产生相同platformArchABI产物集合的 target 也会报错例如同一平台两种等价拼写。配置字段全集UserNapiConfig包括binaryName、packageName、targets、npmClient、rootPublisher、constEnum、runtimeStringEnum、dtsHeader、dtsHeaderFile与wasm子配置。WASI/wasm 子配置wasm字段config.ts包含initialMemory初始线性内存单位 64 KiB 页默认 4000 页约 250 MiBdeferred workerd 加载器默认 1024 页64 MiBthreadlessInitialMemory仅作用于无线程wasm32-wasip1加载器Node CJS、浏览器、deferred workerd未设置时回落到initialMemory线程加载器共享同一块shared: true内存并按整个线程池预分配而线程无关加载器走可增长ArrayBuffer因而能适配 workerd 这类 128 MiB 硬隔离上限的主机maximumMemory最大内存默认 65536 页4 GiBinitialMemory不能超过它越界会抛错校验见 resolveWasmMemoryoptionalDependency生成 WASI 包是否声明为根包的可选依赖——当原生目标存在时默认false避免消费者无谓下载.wasm当 WASI 是唯一目标时默认trueasyncRuntime默认false开启后生成的 node/browser/workerd 加载器会引导napi-async-runtime的 CurrentThread JavaScript 宿主并与绑定实际导出的宿主契约交叉校验不匹配时加载期报ERR_NAPI_ASYNC_RUNTIME_BINDING_MISMATCHbrowserfs是否在浏览器使用 fs 模块、asyncInit是否异步初始化 wasm、buffer是否向 emnapi 上下文注入buffer、errorEventworker 中错误是否派发自定义事件。仓库 examples/napi/package.json 是一个真实配置样例napi: { binaryName: example, wasm: { initialMemory: 16384, browser: { fs: true, buffer: true } }, dtsHeader: type MaybePromiseT T | PromiseT, dtsHeaderFile: ./dts-header.d.ts, targets: [ wasm32-wasip1, wasm32-wasip1-threads ] }注意dtsHeader与dtsHeaderFile同时给出时以dtsHeaderFile为准见 config.ts 的字段注释。底层执行链路一次napi build发生了什么buildProjectcli/src/api/build.ts是整条管线的核心主要环节包括读取并合并配置调用readNapiConfig读取package.json/独立配置文件得到目标列表与构建参数执行 cargo 构建按--target、--release、--profile、--features等参数派生 cargo 命令必要时处理 WASI SDK、emnapi 归档目录选择、交叉编译子命令替换类型定义生成通过napi-derive的typedef元数据生成.d.ts开启--dts-cache时缓存目录由 getTypeDefCacheFolder 计算——位于{targetDir}/napi-rs/{crateName}-{hash}hash 由 CLI 版本、manifest 路径、cargo 依赖图指纹getCargoDependencyGraphFingerprint对解析后的依赖树做 SHA-256、目标三元组、profile、feature 选择、cargo 配置与环境变量等综合得出任何一项变化都会使缓存失效从而保证类型定义与当前源码严格一致JS binding 生成按formatesm/commonjs生成加载器模板createCjsBinding/createEsmBinding见 templates/index.ts并对 WASI 目标生成 node/browser/deferred workerd 等多套加载器与.d.cts声明产物落盘与清理按createArtifactDestinationName规则命名后写入--output-dir并清理不再需要的旧 WASI 产物collectStaleWasiBuildOutputNames。上述行为均有测试覆盖build pipeline generates bindings and artifacts等用例位于 cli/src/api/tests/build.spec.tsresolveBuildFormat handles defaults, aliases, and conflicts同文件 L2472验证了格式默认值与别名冲突处理。典型使用场景本地开发debug 快速构建napi build # debug 构建 napi build --watch # 监听变化持续构建发布构建release 多平台napi build --release --platform --js-package-name my-pkg napi build --release --platform --format esm交叉编译示例# Linux 宿主构建 macOS/其他非 Windows 目标需 zig 在 PATH napi build --release --cross-compile --target aarch64-apple-darwin # Linux 宿主构建 Windows MSVC 目标首次使用自动安装 cargo-xwin napi build --release --cross-compile --target x86_64-pc-windows-msvc # 使用 napi-rs/cross-toolchain 的预编译 gcc 工具链 napi build --release --use-napi-cross --target aarch64-unknown-linux-gnu以上交叉编译方式互斥组合使用会被校验拒绝。在 npm scripts 中落地参考仓库根 package.json发布期脚本可写为scripts: { build: napi build --release --platform, build:debug: napi build, build:wasm: napi build --release --target wasm32-wasip1 }与其他 napi 命令的衔接napi build只负责编译与产物生成。构建完成后后续的包工程化通常由同仓库 cli/docs 下的其他命令承接napi create-npm-dirs生成各平台 npm 包目录见 create-npm-dirs.md、napi universalize合并多平台二进制为通用包见 universalize.md、napi pre-publish校验发布前配置见 pre-publish.md形成编译 → 打包 → 校验 → 发布的完整闭环。小结napi build通过一组设计清晰的选项把cargo 编译 加载器生成 类型导出 跨平台/交叉编译 缓存与签名整合为单条命令路径与产物选项控制工程布局--platform与--format决定发布形态三套交叉编译机制适配不同 CI 场景napi配置文件则沉淀工程级默认值。理解其选项语义与底层命名、缓存、校验规则是稳定产出可发布的 Node-API 原生模块的前提。赞分享开发工具后端【免费下载链接】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-rs 的 Node-API 工程化实践napi rs/cli 全解析从版本演进看 napi rs 的 Node API 工程化实践 napi rs/cli 是 napi rs 生态的命令行工具开发工具后端MediaPipe快速上手指南5分钟让设备端跑起人脸、手势与姿态检测MediaPipe快速上手指南5分钟让设备端跑起人脸、手势与姿态检测 你的应用需要实时的人脸检测、手势识别或姿态跟踪但又不想自己折腾模型部署MediaPi开发工具后端终极跨平台指南napi-rs在Windows/macOS/Linux的完整编译部署方案终极跨平台指南napi rs在Windows/macOS/Linux的完整编译部署方案 napi rs是一个通过Node API在Rust中构建编译型Node开发工具后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考