node-gyp - Node.js 原生插件构建工具

这是原始优秀 node-gyp 的一个分支，仅添加了一项功能：支持 Node v12。Electron 维护者采取此步骤是为了确保我们的社区能够在 macOS Sequoia 上轻松构建其 Electron 应用。以下是具体情况：

• Python 3.12 已移除 distutils，而 v10 以下版本的 node-gyp 依赖此模块。
• macOS Sequoia 将其默认 Python 版本更新至 3.12。
• 安装 Node 原生插件时，许多代码库突然出现 ModuleNotFoundError: No module named 'distutils' 错误消息，对于不全面了解所涉及依赖链的人来说，这些消息难以理解。

这让 Electron 维护者面临以下选择：

1. 告知社区手动安装 Python 3.11 或 setuptools。虽然这能解决问题，但需要用户手动干预，并且要求我们的用户首先搜索错误消息。
2. 升级到 node-gyp v10。这将需要提升 @electron/rebuild 的最低 Node.js 版本要求，进而影响所有依赖它的其他包，导致整个生态系统出现重大版本更新。同样，若用户不手动执行重大版本升级，此问题也无法解决。
3. 分叉 node-gyp v10，使其兼容 Node.js v12，并仅修补我们的工具：我们选择此选项，以便以最快、最无痛的方式为用户提供修复。

Electron 已将 Node.js 版本要求的重大更新列入路线图。一旦完成，我们将停止此分支的维护，并回归使用原始的 node-gyp。

原始自述文件

node-gyp 是一个用 Node.js 编写的跨平台命令行工具，用于编译 Node.js 的原生插件模块。它包含 gyp-next 项目的一份 vendored 副本，该项目先前由 Chromium 团队使用，并经过扩展以支持 Node.js 原生插件的开发。

请注意，node-gyp 不 用于构建 Node.js 本身。

所有当前和 LTS 目标版本的 Node.js 均受支持。根据系统上实际安装的 Node.js 版本，node-gyp 会下载目标版本所需的开发文件或头文件。稳定 Node.js 版本列表可在 Node.js 官网 上找到。

特性

• 相同的构建命令可在任何受支持的平台上运行
• 支持针对不同版本的 Node.js 进行构建

安装

您可以使用 npm 安装 node-gyp：

npm install -g node-gyp

根据您的操作系统，您需要安装以下工具：

在 Unix 系统上

• 受支持的 Python 版本
  • make
  • 合适的 C/C++ 编译器工具链，例如 GCC

在 macOS 系统上

• 受支持的 Python 版本
  • Xcode 命令行工具，它会安装 clang、clang++ 和 make。
    • 通过运行 xcode-select --install 单独安装 Xcode 命令行工具。或者
    • 如果您已安装 完整的 Xcode，可以通过菜单 Xcode -> Open Developer Tool -> More Developer Tools... 安装命令行工具。

在 Windows 系统上

使用 Chocolatey 安装工具：

choco install python visualstudio2022-workload-vctools -y

或者手动安装并配置 Python 和 Visual Studio 工具：

• 从 Microsoft Store 安装当前的 Python 版本。

  • 安装 Visual C++ 生成环境：对于 Visual Studio 2019 或更高版本，请使用 Visual Studio Community 中的“使用 C++ 的桌面开发”工作负载。对于 Visual Studio 2019 之前的版本，请安装 Visual Studio Build Tools 并勾选“Visual C++ 生成工具”选项。

如果上述步骤对您不起作用，请访问 Microsoft 的 Windows Node.js 指南 以获取更多提示。

要在 Windows on ARM 上定位原生 ARM64 Node.js，请添加组件“用于 ARM64 的 Visual C++ 编译器和库”以及“用于 ARM64 的 Visual C++ ATL”。

要在 Windows on ARM 上使用原生 ARM64 C++ 编译器，请确保您已安装 Visual Studio 2022 17.4 或更高版本。

建议安装以下 PowerShell 模块：VSSetup，使用命令 Install-Module VSSetup -Scope CurrentUser。 这将使 Visual Studio 检测逻辑使用更灵活且更易访问的方法，避免 PowerShell 的“ConstrainedLanguage”模式。

配置 Python 依赖项

node-gyp 要求您已安装 受支持的 Python 版本。 如果您安装了多个 Python 版本，可以通过以下方式之一指定 node-gyp 应使用的版本：

1. 通过设置 --python 命令行选项，例如：

node-gyp <command> --python /path/to/executable/python

2. 如果通过 npm 调用 node-gyp，并且你安装了多个 Python 版本，那么可以将 npm_config_python 环境变量设置为相应的路径：

export npm_config_python=/path/to/executable/python

    或者在 Windows 上：

py --list-paths  # To see the installed Python versions
set npm_config_python=C:\path\to\python.exe  # CMD
$Env:npm_config_python="C:\path\to\python.exe"  # PowerShell

3. 如果 PYTHON 环境变量被设置为某个 Python 可执行文件的路径，那么只要该版本是受支持的，就会使用该版本。

4. 如果 NODE_GYP_FORCE_PYTHON 环境变量被设置为某个 Python 可执行文件的路径，它将替代任何其他已配置或内置的 Python 搜索路径被使用。如果该版本不兼容，将不会进行进一步的搜索。

为第三方 Node.js 运行时构建

当为第三方 Node.js 运行时（如 Electron）构建模块时，由于这些运行时的构建配置与官方 Node.js 发行版不同，你应该使用 --dist-url 或 --nodedir 标志来指定要构建的运行时的头文件。

此外，当传递 --dist-url 或 --nodedir 标志时，node-gyp 将使用头文件发行版中附带的 config.gypi 来生成构建配置，这与默认模式（使用运行中的 Node.js 实例的 process.config 对象）不同。

某些旧版本的 Electron 在其头文件发行版中附带了格式不正确的 config.gypi，此时你可能需要向 node-gyp 传递 --force-process-config 以解决配置错误。

如何使用

要编译你的原生插件，请先进入其根目录：

cd my_node_addon

下一步是为当前平台生成相应的项目构建文件。可使用 configure 命令执行此操作：

node-gyp configure

Visual C++ Build Tools 2015 的自动检测功能无法正常工作，因此需要添加 --msvs_version=2015（按照上述配置通过 npm 运行时则无需添加）：

node-gyp configure --msvs_version=2015

注意：configure 步骤会在当前目录中查找 binding.gyp 文件进行处理。有关创建 binding.gyp 文件的说明，请参见下文。

现在，build/ 目录中会生成一个 Makefile（在 Unix 平台上）或 vcxproj 文件（在 Windows 上）。接下来，调用 build 命令：

node-gyp build

现在您已经拥有编译好的 .node 绑定文件了！编译后的绑定文件会根据构建模式，最终输出到 build/Debug/ 或 build/Release/ 目录中。此时，您可以使用 Node.js require 该 .node 文件并运行测试了！

注意： 若要创建绑定文件的 Debug 版本，请在运行 configure、build 或 rebuild 命令时传递 --debug（或 -d）开关。

binding.gyp 文件

binding.gyp 文件以类 JSON 格式描述构建模块的配置。此文件应放置在您的包的根目录下，与 package.json 同级。

一个适用于构建 Node.js 插件的基础 gyp 文件示例如下：

{
  "targets": [
    {
      "target_name": "binding",
      "sources": [ "src/binding.cc" ]
    }
  ]
}

进一步阅读

docs 目录包含有关 node-gyp 特定主题的额外文档，如果您在使用 node-gyp 安装或构建插件时遇到问题，这些文档可能会有所帮助。

以下是有关 Node.js 原生插件和编写 gyp 配置文件的一些其他资源：

• “Going Native”，nodeschool.io 教程
• “Hello World” node 插件示例
• gyp 用户文档
• gyp 输入格式参考
• “实际应用中的 binding.gyp 文件” 维基页面

命令

node-gyp 支持以下命令：

命令	描述
help	显示帮助对话框
build	调用 make/msbuild.exe 并构建原生插件
clean	如果 build 目录存在，则将其删除
configure	为当前平台生成项目构建文件
rebuild	连续运行 clean、configure 和 build
install	安装指定版本的 Node.js 头文件
list	列出当前已安装的 Node.js 头文件版本
remove	删除指定版本的 Node.js 头文件

命令选项

node-gyp 接受以下命令选项：

命令	描述
-j n, --jobs n	并行运行 make。值为 max 时将使用所有可用的 CPU 核心
--target=v6.2.1	要构建的 Node.js 版本（默认为 process.version）
--silly, --loglevel=silly	将所有进度记录到控制台
--verbose, --loglevel=verbose	将大部分进度记录到控制台
--silent, --loglevel=silent	不在控制台记录任何内容
debug, --debug	生成调试版本（默认为 Release）
--release, --no-debug	生成发布版本
-C $dir, --directory=$dir	在不同目录中运行命令
--make=$make	覆盖 make 命令（例如 gmake）
--thin=yes	启用精简静态库
--arch=$arch	设置目标架构（例如 ia32）
--tarball=$path	从本地 tarball 获取头文件
--devdir=$path	SDK 下载目录（默认为操作系统缓存目录）
--ensure	如果头文件已存在，则不重新安装
--dist-url=$url	从自定义 URL 下载头文件 tarball
--proxy=$url	设置用于下载头文件 tarball 的 HTTP(S) 代理
--noproxy=$urls	设置下载头文件 tarball 时忽略代理的 URL
--cafile=$cafile	覆盖默认 CA 链（用于下载 tarball）
--nodedir=$path	设置 node 源代码的路径
--python=$path	设置 Python 二进制文件的路径
--msvs_version=$version	设置 Visual Studio 版本（仅 Windows）
--solution=$solution	设置 Visual Studio 解决方案版本（仅 Windows）
--force-process-config	强制使用运行时的 process.config 对象生成 config.gypi 文件

配置

环境变量

对于上面列出的任何命令选项，请使用 npm_config_OPTION_NAME 格式（选项名称中的连字符应替换为下划线）。

例如，要将 devdir 设置为 /tmp/.gyp，您需要：

在 Unix 系统上运行以下命令：

export npm_config_devdir=/tmp/.gyp

或者在 Windows 上执行以下命令：

set npm_config_devdir=c:\temp\.gyp

v9 之前版本的 npm 配置

对于上述列出的任何命令选项，均使用 OPTION_NAME 格式。

例如，要将 devdir 设置为 /tmp/.gyp，可以运行：

npm config set [--global] devdir /tmp/.gyp

注意： 通过 npm 设置的配置仅在通过 npm 运行 node-gyp 时使用，直接运行 node-gyp 时不适用。

许可证

node-gyp 采用 MIT 许可证。详情请参见 LICENSE 文件。