On this page

原生插件的一个限制是它们必须针对每个目标平台和架构进行编译。如果没有预构建的二进制文件，每个安装你的包的用户都必须在他们的机器上拥有可用的 C/C++ 工具链。

🌐 One of the limitations of native addons is that they must be compiled for each target platform and architecture. Without pre-built binaries, every user who installs your package must have a working C/C++ toolchain on their machine.

node-pre-gyp 通过让你提前构建二进制文件、将它们上传到远程位置，并在安装时让用户下载正确的二进制文件来解决这个问题——只有在没有可用的匹配二进制文件时才会回退到从源码编译。

请注意，Node-API 支持已在 node-pre-gyp 0.8.0 版本中添加。

此页描述了支持 node-pre-gyp 所需对 Node-API 插件进行的更改。

🌐 This page describes the changes required to a Node-API addon to support node-pre-gyp.

🌐 Amazon S3

默认情况下，node-pre-gyp 会将二进制文件上传到 Amazon S3。

🌐 By default, node-pre-gyp uploads binaries to Amazon S3.

＞ node-pre-gyp-github 模块改为支持发布到 GitHub Releases。

🌐 Amazon S3 Requirements

在上传之前，你需要：

🌐 Before uploading you need:

  1. 一个亚马逊网络服务账户。
  2. 具有上传到 S3 权限的 IAM 用户或角色。
  3. 一个 S3 存储桶 用于托管二进制文件。

🌐 AWS Credentials

切勿在你的仓库中存储凭证。node-pre-gyp 支持在开发过程中提供凭证的两种常见方法：

🌐 Never store credentials in your repository. node-pre-gyp supports two common approaches for providing credentials during development:

  1. 一个 ~/.node_pre_gyprc 文件：

    {
  "accessKeyId": "xxx",
  "secretAccessKey": "xxx"
}
    JSON

  2. 环境变量：

    export node_pre_gyp_accessKeyId=xxx
export node_pre_gyp_secretAccessKey=xxx
    Shell

对于 CI 环境，建议使用 IAM 角色或短期凭证，而不是长期有效的访问密钥。有关其他选项，请参阅 node-pre-gyp 凭证文档。

🌐 For CI environments, prefer IAM roles or short-lived credentials rather than long-lived access keys. See the node-pre-gyp credentials documentation for additional options.

🌐 The dependencies and devDependencies properties

该包现在已在 @mapbox 范围下发布。在上传步骤中将 @aws-sdk/client-s3 用作开发依赖。

🌐 The package is now published under the @mapbox scope. Use @aws-sdk/client-s3 as a dev dependency for the upload step.

"dependencies": {
  "@mapbox/node-pre-gyp": "^1.0.0"
},
"devDependencies": {
  "@aws-sdk/client-s3": "^3.0.0"
}
JSON

🌐 The scripts property

install 脚本应该使用 --fallback-to-build 调用 node-pre-gyp，以便那些没有可用预编译二进制文件的用户仍然可以在本地进行编译：

🌐 The install script should invoke node-pre-gyp with --fallback-to-build so that users who don't have a pre-built binary available can still compile locally:

"scripts": {
  "install": "node-pre-gyp install --fallback-to-build"
}
JSON

🌐 The binary property

binary 属性告诉 node-pre-gyp 你的插件支持哪些 Node-API 版本以及在哪里查找/上传二进制文件：

🌐 The binary property tells node-pre-gyp which Node-API versions your addon supports and where to find/upload binaries:

"binary": {
  "module_name": "your_module",
  "module_path": "./lib/binding/napi-v{napi_build_version}",
  "remote_path": "./{module_name}/v{version}/{configuration}/",
  "package_name": "{platform}-{arch}-napi-v{napi_build_version}.tar.gz",
  "host": "https://your_bucket.s3.us-west-1.amazonaws.com",
  "napi_versions": [3]
}
JSON

将 module_name 设置为有效的 C 标识符。napi_versions 数组列出了要构建的 Node-API 版本；3 是大多数插件的合理最小值。

🌐 Set module_name to a valid C identifier. The napi_versions array lists which Node-API versions to build for; 3 is a reasonable minimum for most addons.

请参阅 node-pre-gyp 文档 以获取完整参考，包括 Node-API 考虑事项。

🌐 See the node-pre-gyp docs for a complete reference, including Node-API considerations.

🌐 New target

添加一个后期构建目标，将编译后的二进制文件复制到 module_path 指定的路径：

🌐 Add a post-build target to copy the compiled binary to the path specified by module_path:

{
  "target_name": "action_after_build",
  "type": "none",
  "dependencies": ["<(module_name)"],
  "copies": [
    {
      "files": ["<(PRODUCT_DIR)/<(module_name).node"],
      "destination": "<(module_path)"
    }
  ]
}
JSON

在第一个目标的 defines 中包含 Node-API 版本，以便头文件正确配置自己：

🌐 Include the Node-API version in the first target's defines so the header files configure themselves correctly:

"defines": [
  "NAPI_VERSION=<(napi_build_version)"
]
JSON

🌐 JavaScript updates

加载本地二进制文件的 JavaScript 代码必须动态解析到正确 .node 文件的路径：

🌐 JavaScript code that loads the native binary must dynamically resolve the path to the correct .node file:

const binary = require('@mapbox/node-pre-gyp');
const path = require('path');
const bindingPath = binary.find(
  path.resolve(path.join(__dirname, './package.json'))
);
const binding = require(bindingPath);
JavaScript

🌐 Build

一切就绪后，从源代码构建：

🌐 Once everything is in place, build from source:

npm install --build-from-source

🌐 Package and publish

./node_modules/.bin/node-pre-gyp package
./node_modules/.bin/node-pre-gyp publish
Shell

🌐 CI and automated builds

使用 GitHub Actions 为多个平台和架构构建、测试和发布二进制文件。典型的工作流矩阵涵盖 ubuntu-latest、macos-latest 和 windows-latest，以及你需要的任何架构变体（例如 x64、arm64）。请参阅 node-pre-gyp 仓库中的 示例工作流配置。

🌐 Use GitHub Actions to build, test, and publish binaries for multiple platforms and architectures. A typical workflow matrix covers ubuntu-latest, macos-latest, and windows-latest, plus any architecture variants you need (e.g. x64, arm64). See the node-pre-gyp repository for example workflow configurations.