NAPI 配置

将配置放在 package.json 的 napi 键下：

package.json

json

{
  "name": "@scope/addon",
  "napi": {
    "binaryName": "addon",
    "targets": ["x86_64-unknown-linux-gnu", "aarch64-apple-darwin"]
  }
}

提供 --config-path 的命令也可以读取独立 JSON 文件。两种来源同时存在时，以独立配置为准。所有用户提供的字段都是可选的。

Schema

{
  napi?: {
    binaryName?: string
    targets?: string[]
    packageName?: string
    npmClient?: string
    constEnum?: boolean
    runtimeStringEnum?: boolean
    dtsHeader?: string
    dtsHeaderFile?: string
    wasm?: {
      initialMemory?: number
      maximumMemory?: number
      browser?: {
        fs?: boolean
        asyncInit?: boolean
        buffer?: boolean
        errorEvent?: boolean
      }
    }
  }
}

字段与实际默认值

字段	默认值	描述
`binaryName`	`index`	生成的原生与 WASI 文件的基本名称。平台构建会生成类似 `index.win32-x64-msvc.node` 的名称。
`targets`	`[]`	项目打包并发布的 target triples。这不是多目标构建命令。
`packageName`	根 `package.json` 的 `name`	生成的加载器和各平台包使用的包名。当 JavaScript 包名与根包元数据不同时可覆盖它；参见构建：JS 包名。
`npmClient`	`npm`	发布各平台包等 npm 操作所使用的命令。
`constEnum`	`true`	生成 TypeScript `const enum` 声明。当配置和 CLI 都未覆盖时，类型生成的实际默认值是 `true`。
`runtimeStringEnum`	`false`	与 `constEnum: false` 一起使用时，将 `#[napi(string_enum)]` 生成为运行时 `enum`，而不是仅存在于类型层的字符串联合。`constEnum` 为 `true` 时不起作用。
`dtsHeader`	`undefined`	前置到生成的声明文件的字符串。
`dtsHeaderFile`	`undefined`	一个相对于命令工作目录的文件路径，其内容会前置到生成的声明文件。它的优先级高于 `dtsHeader`。
`wasm.initialMemory`	`4000` pages	初始共享 WebAssembly 内存，约 250 MiB。
`wasm.maximumMemory`	`65536` pages	最大共享 WebAssembly 内存，4 GiB。
`wasm.browser.fs`	`false`	在浏览器 WASI 绑定中包含内存文件系统和文件系统代理。
`wasm.browser.asyncInit`	`false`	浏览器绑定使用 emnapi 的异步模块实例化路径。
`wasm.browser.buffer`	`false`	导入 `Buffer` 并注入浏览器绑定所使用的 emnapi 上下文。
`wasm.browser.errorEvent`	`false`	将 worker 故障转发为浏览器 `napi-rs-worker-error` `CustomEvent`，其中包含捕获的 worker 错误输出。

一个 WebAssembly 内存页为 64 KiB。这些内存设置会写入生成的 Node 和浏览器 WASI 加载器；它们不是 Cargo 内存限制。

INFO

runtimeStringEnum: true 要求 constEnum: false。对应的构建标志是 --runtime-string-enum --no-const-enum。

`targets` 控制什么

targets 驱动打包流程：

napi create-npm-dirs 为每个目标创建一个 npm 目录。
napi artifacts 将构建文件放入这些目录。
napi pre-publish 设置版本并发布这些包。
WASI 目标会启用 <binaryName>.wasi.cjs 及相关浏览器和 worker 文件的生成。

设置 targets 不会让 napi build 编译其中每一项。每次构建只生成一个由 --target、CARGO_BUILD_TARGET 或宿主机默认值选择的目标。同样，交叉编译标志（--use-napi-cross、--cross-compile 和 --use-cross）没有对应的配置字段。

目标列表也不会创建任意 CI 任务。napi new 只会过滤所选模板中已经存在的任务。如果添加其他可接受目标，请同时添加其构建任务，并单独验证运行时。参见支持与兼容性和交叉编译。

已弃用的 v2 字段

CLI 仍会读取这些字段以保持兼容，但新项目不应再使用：

已弃用	替代项
`napi.name`	`napi.binaryName`
`napi.triples.defaults` 和 `napi.triples.additional`	`napi.targets`

v3 配置规范化器不会读取旧的嵌套字段 napi.package.name。请显式把该值移到 napi.packageName。

什么是 target triple？

参见 Rust 平台支持和 LLVM 交叉编译。target triple 描述产物的架构、供应商、操作系统和 ABI，例如：

text

x86_64-unknown-linux-gnu
└─ arch  └ vendor └ system └ ABI

确定要发布哪些 target triple 后，请使用交叉编译为每个目标选择并验证构建机制。

# NAPI 配置

# Schema

# 字段与实际默认值

# targets 控制什么

# 已弃用的 v2 字段

# 什么是 target triple？