# Build

构建 NAPI-RS 项目

# 用法

# CLI
napi build [--options]

// Programmatically
import { NapiCli } from '@napi-rs/cli'

new NapiCli().build({
  // options
})

# 选项

# 交叉编译标志

napi build 有三个交叉编译标志：--use-napi-cross、--cross-compile（-x）和 --use-cross。三者都是实验性的：行为可能在次要版本之间发生变化。

推荐的标志是：在 Linux x64/arm64 宿主机上构建 Linux glibc 目标用 --use-napi-cross，从非 Windows 宿主机构建 Windows MSVC 目标以及构建 musl 目标用 --cross-compile（-x）。当首选配置在你的宿主机上不可用时，-x 也是 glibc、macOS 和 FreeBSD 目标的兜底方案。Android、WASI 和 OpenHarmony 目标完全不需要交叉编译标志：CLI 会根据平台环境变量配置它们的工具链。--use-cross 是遗留方案，不推荐使用，基于 Docker 镜像的构建也已弃用。本页是各标志具体行为的参考。要为你的宿主机和目标选对标志，参见交叉编译。Alpine/musl 相关细节参见 FAQ。

每个标志只改变构建的一件事：

# 只能选择一个

# 前置条件

# 示例

每个标志一条可复制粘贴的命令：

# Linux glibc targets, from a Linux x64/arm64 host
napi build --release --target aarch64-unknown-linux-gnu --use-napi-cross

# Windows MSVC from a macOS/Linux host, musl, or the zigbuild fallback cases
napi build --release --target x86_64-unknown-linux-musl --cross-compile

# Legacy container build (not recommended)
napi build --release --target x86_64-unknown-linux-gnu --use-cross

# napi build 实际运行了什么

napi build 是对一条派生命令加一组环境变量的封装。本节把两者都列出来。

# 命令

--cross-compile 按目标的平台选择 cargo-xwin，但从非 Windows 宿主机只接受 Windows MSVC 目标。Windows GNU 和 gnullvm 目标会在产生构建副作用前被拒绝，因为 cargo-xwin 无法提供它们的工具链。请不加 -x，分别使用 mingw-w64 或 llvm-mingw 构建；参见各目标的构建方法中的 windows-gnu 说明。每个非 Windows 目标都走 cargo-zigbuild；CLI 不维护 zigbuild 支持目标的列表，即使目标与宿主机相同也照样使用。

如果设置了 CARGO 环境变量，CLI 会在所有模式下改为派生该二进制。与 --use-cross 或 --cross-compile 一起使用时，CLI 会警告该覆盖会替换所选机制依赖的二进制。

# RUSTFLAGS

• 任何 *musl* 目标：CLI 向 RUSTFLAGS 追加 -C target-feature=-crt-static。
• --strip：CLI 追加 -C link-arg=-s。

两者都通过导出的 RUSTFLAGS 环境变量生效。Cargo 中环境变量的优先级高于 .cargo/config.toml 里的 rustflags，因此一旦 CLI 导出了它，你 .cargo/config.toml 中的 rustflags 就会被忽略。如果需要额外的标志，请把它们加到 RUSTFLAGS 环境变量里，而不是 .cargo/config.toml。

# C 编译器

同时设置 TARGET_CC 和 CC 时，TARGET_CC 生效（自 @napi-rs/cli 3.0.0-alpha.92 起）。

# 不常见目标的默认链接器

在不使用 --cross-compile 时，下列目标的 CARGO_TARGET_<T>_LINKER 会被指向一个需要你自行安装的交叉 gcc。CLI 只设置环境变量而不做检查：如果该二进制缺失，构建会在链接阶段失败。你自己设置的 CARGO_TARGET_<T>_LINKER 环境变量始终优先。使用 --cross-compile 时会跳过这张表 —— 链接交给 zig 或 xwin。

# Android、WASI 和 OpenHarmony

只要目标平台匹配，这些目标就会从 CLI 获得工具链环境变量 —— 无论是否传入任何交叉编译标志 —— 但每个平台有自己的条件：

• Android：在非 Android 宿主机上，linker/CC/AR 环境变量由 ANDROID_NDK_LATEST_HOME 构造。如果该变量缺失，CLI 会在启动 Cargo 前停止，而不是导出无效的工具路径。当宿主机本身就是 Android 时，整套设置（包括对该变量的要求）都会被跳过。
• WASI：EMNAPI_LINK_DIR 始终被设置为自带的 emnapi（当 emnapi、@emnapi/core 和 @emnapi/runtime 的版本不匹配时 CLI 会报错）。只有当设置了 WASI_SDK_PATH 且该目录存在时，才会设置 wasi-sdk 的 linker/CC 环境变量 —— 否则链接回退到 cargo 的默认值，即 rustup 自带的 rust-lld。
• OpenHarmony：环境变量由 $OHOS_SDK_PATH/native 构造，当 OHOS_SDK_PATH 未设置时改用 OHOS_SDK_NATIVE。两者都未设置时，CLI 打印警告且什么都不设置。

# 向 Cargo 传递标志

-- 之后的标志会透传给 cargo build 命令。例如：

napi build -- --locked

这会把 --locked 标志传给 cargo build，最终执行 cargo build --locked。

# 构建 Cargo 可执行文件

--bin <name> 会选择一个 Cargo 二进制目标，包括同时包含 cdylib 的包。CLI 会把 --bin <name> 传给 Cargo，并使用普通名称（Windows 上带 .exe）把生成的可执行文件复制到 --output-dir：

[[bin]]
name = "my-tool"
path = "src/main.rs"

napi build --bin my-tool --release --output-dir dist
./dist/my-tool

该模式不会生成 .node 插件、JavaScript 加载器或 TypeScript 声明；构建后的绑定生成只对 cdylib 运行。

未传入 --bin 时，包中的 cdylib 仍是首选插件目标。在 workspace 中，如果二进制目标不在 --manifest-path 默认选择的包内，请组合使用 --package <cargo-package> 和 --bin <name>。

# 关于 --js-package-name 的说明

在深入一节中，我们建议你把包发布在 npm scope 下。但如果你正在迁移一个不在 npm scope 下的既有包，或者你就是不想把包放在 npm scope 下，那么在发布各平台原生包时可能会触发 npm spam detection，比如 snappy-darwin-x64、snappy-darwin-arm64 等等……

这种情况下，你可以把平台包发布到 npm scope 下来避免 npm spam detection。你的用户也无需关心 optionalDependencies 里的平台原生包。以 snappy 为例，用户只需通过 yarn add snappy 安装它，而平台原生包都在 @napi-rs scope 下：

{
  "name": "snappy",
  "version": "7.0.0",
  "optionalDependencies": {
    "@napi-rs/snappy-win32-x64-msvc": "7.0.0",
    "@napi-rs/snappy-darwin-x64": "7.0.0",
    "@napi-rs/snappy-linux-x64-gnu": "7.0.0",
    "@napi-rs/snappy-linux-x64-musl": "7.0.0",
    "@napi-rs/snappy-linux-arm64-gnu": "7.0.0",
    "@napi-rs/snappy-win32-ia32-msvc": "7.0.0",
    "@napi-rs/snappy-linux-arm-gnueabihf": "7.0.0",
    "@napi-rs/snappy-darwin-arm64": "7.0.0",
    "@napi-rs/snappy-android-arm64": "7.0.0",
    "@napi-rs/snappy-android-arm-eabi": "7.0.0",
    "@napi-rs/snappy-freebsd-x64": "7.0.0",
    "@napi-rs/snappy-linux-arm64-musl": "7.0.0",
    "@napi-rs/snappy-win32-arm64-msvc": "7.0.0"
  }
}

针对这种情况，@napi-rs/cli 提供了 --js-package-name 来覆盖生成的包加载逻辑。例如在 snappy 中，我们的 package.json 是这样的：

{
  "name": "snappy",
  "version": "7.0.0",
  "napi": {
    "binaryName": "snappy"
  }
}

不使用 --js-package-name 标志时，@napi-rs/cli 会生成这样的 JavaScript 绑定来为你加载平台原生包：

switch (platform) {
  case 'darwin':
    switch (arch) {
      case 'x64':
        localFileExisted = existsSync(join(__dirname, 'snappy.darwin-x64.node'))
        try {
          if (localFileExisted) {
            nativeBinding = require('./snappy.darwin-x64.node')
          } else {
            nativeBinding = require('snappy-darwin-x64') 
          }
        } catch (e) {
          loadError = e
        }
        break
      case 'arm64':
        localFileExisted = existsSync(join(__dirname, 'snappy.darwin-arm64.node'))
        try {
          if (localFileExisted) {
            nativeBinding = require('./snappy.darwin-arm64.node')
          } else {
            nativeBinding = require('snappy-darwin-arm64') 
          }
        } catch (e) {
          loadError = e
        }
        break
      default:
        throw new Error(`Unsupported architecture on macOS: ${arch}`)
    }
    break
    ...
}

这不是我们想要的。所以用 --js-package-name 覆盖生成的 JavaScript 绑定文件中的 package name：napi build --release --platform --js-package-name @napi-rs/snappy。生成的 JavaScript 文件就会变成：

switch (platform) {
  case 'darwin':
    switch (arch) {
      case 'x64':
        localFileExisted = existsSync(join(__dirname, 'snappy.darwin-x64.node'))
        try {
          if (localFileExisted) {
            nativeBinding = require('./snappy.darwin-x64.node')
          } else {
            nativeBinding = require('@napi-rs/snappy-darwin-x64') 
          }
        } catch (e) {
          loadError = e
        }
        break
      case 'arm64':
        localFileExisted = existsSync(join(__dirname, 'snappy.darwin-arm64.node'))
        try {
          if (localFileExisted) {
            nativeBinding = require('./snappy.darwin-arm64.node')
          } else {
            nativeBinding = require('@napi-rs/snappy-darwin-arm64') 
          }
        } catch (e) {
          loadError = e
        }
        break
      default:
        throw new Error(`Unsupported architecture on macOS: ${arch}`)
    }
    break
    ...
}