# @electron/node-gyp 中文文档

规范地址：https://npmcn.com/package/%40electron/node-gyp/

版本：10\.2\.0-electron\.2
npm 元数据更新时间：2024-10-08T17:26:26.698Z
中文译文更新时间：2026-11-13T11:56:58.591Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40electron/node-gyp
原文对照：https://npmcn.com/package/%40electron/node-gyp/?lang=original
项目主页：https://github.com/nodejs/node-gyp#readme
源码仓库：https://github.com/nodejs/node-gyp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.9 MB，110 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=12\.13\.0
- 运行依赖：10 个
- 首次发布：2024-09-24T07:04:27.270Z
- 最新版本发布：2024-10-08T17:26:26.499Z
- 近 30 天下载量：1577077（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 0 个）

## 中文简介

节点.js 本地添加构建工具

## 安装

```sh
npm install @electron/node-gyp
```

也可以使用：`pnpm add @electron/node-gyp`、`yarn add @electron/node-gyp`、`bun add @electron/node-gyp`

## README

# `node-gyp` - 节点.js 土生土长的建筑工具

这是原作的叉子 非常好 `node-gyp` 仅添加了一个功能: 支持Node v12. Electron维护者采取了这一步骤,以确保我们社区能够轻松地在macOS Sequoia上建造他们的Electron App. 是这样的:

-   Python 3.12 已经删除 `distutils`,哪个 `node-gyp` 取决于v10以下.
-   macOS Sequoia将其默认版本的Python更新为3.12.
-   当安装本地节点加通时,许多代码基础突然显示 `ModuleNotFoundError: No module named 'distutils'` 对不完全了解相关依赖链的人来说 错误信息是加密的

这使得电源维护者有以下选择:

1.  **告诉社区手动安装 Python 3. 11 或 `setuptools`**。在解决这个问题的同时,它需要人工用户干预,并要求我们的用户首先搜索出错误信息.
2.  **升级到 `node-gyp` 第10个**。这需要一个最小节点.js版本,用于 `@electron/rebuild` 进而导致整个生态系统出现重大版本起伏。 如果用户不进行手动主要版本的升级,这个问题也不会解决.
3.  **叉节点-gyp v10,使其与Node.js v12相兼容,只补丁我们的工具**:我们选择了这个选项,以便尽快地和无痛地找到我们的用户.

Electron在它的行进图上在需要的Node.js版本中有一个大版本起伏. 一旦这样,我们就会落下这个叉子 回到原地 `node-gyp`。 。 。 .

# 原始读取器

[![Build Status](https://github.com/nodejs/node-gyp/workflows/Tests/badge.svg?branch=main)](https://github.com/nodejs/node-gyp/actions?query=workflow%3ATests+branch%3Amain) ![npm](https://img.shields.io/npm/dm/node-gyp)

`node-gyp` 是一个跨平台命令行工具,用 Node.js 为 为 Node.js 编译本地添加模块。 里面有一份出售的复制品 [下一页](https://github.com/nodejs/gyp-next) 先前使用的项目 由Chromium团队负责,并推广到支持Node.js本土的发展 补入.

请注意: `node-gyp` 实值 _没有_ 曾自建Node.js.

所有当前和LTS目标版本的Node.js都得到了支持. 取决于实际安装在您的系统中的 Node.js 版本 `node-gyp` 下载目标版本的必要开发文件或标题。 稳定节点.js版本列表可见于 [节点.js网站](https://nodejs.org/en/about/previous-releases)。 。 。 .

## 特征

-   在任何支持的平台上执行相同的构建命令
-   支持针对不同版本的Node.js

## 安装

> \[重要\] Python >= v3.12 要求 `node-gyp` >=v10

您可以安装 `node-gyp` 使用 `npm`数字 :

```bash
npm install -g node-gyp
```

根据您的操作系统, 您需要安装 :

### 在 unix 上

-   [支持的 Python 版本](https://devguide.python.org/versions/)
-   `make`
-   适当的 C/C++ 编译器工具链, 如 [海合会](https://gcc.gnu.org/)

### 在磁盘上

-   [支持的 Python 版本](https://devguide.python.org/versions/)
-   `Xcode Command Line Tools` 将安装 `clang`, (中文(简体) ), `clang++`,以及 `make`。 。 。 .
    -   安装 `Xcode Command Line Tools` 通过运行独立 `xcode-select --install`. -- -- 或 -- --
    -   或者,如果你已经拥有 [已安装全部 Xcode](https://developer.apple.com/xcode/download/),您可以在菜单下安装命令行工具 `Xcode -> Open Developer Tool -> More Developer Tools...`。 。 。 .

### 在窗口上

安装工具 [巧克力质](https://chocolatey.org/)数字 :

```bash
choco install python visualstudio2022-workload-vctools -y
```

或手动安装和配置 Python 和 Visual Studio 工具 :

-   安装当前 [python 的版本](https://devguide.python.org/versions/) 从 [微软存储](https://apps.microsoft.com/store/search?publisher=Python+Software+Foundation)。 。 。 .
    
-   安装可视 C++ 构建环境:对于Visual Studio 2019或以后,使用 `Desktop development with C++` 工作量 [视觉工作室社区](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community)。对于比Visual Studio 2019年年长的版本,安装 [Visual Studio 构建工具](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools) 与 `Visual C++ build tools` 选项.
    

如果以上步骤对你无效,请访问 [微软的Windows节点.js 准则](https://github.com/Microsoft/nodejs-guidelines/blob/master/windows-environment.md#compiling-native-addon-modules) 额外提示.

在ARM上的Windows上瞄准本地的ARM64节点.js,加入"ARM64的Visual C++编译器和库"和"ARM64的Visual C++ ATL"等组件.

要在 ARM 上的 Windows 上使用本地的 ARM64 C++ 编译器, 请确保您有 Visual Studio 2022 [17.4 或以后](https://devblogs.microsoft.com/visualstudio/arm64-visual-studio-is-officially-here/) 已安装.

建议安装以下Powershell模块: [虚拟](https://github.com/microsoft/vssetup.powershell) 使用 `Install-Module VSSetup -Scope CurrentUser`。 。 。 . 这将使得Visual Studio的检测逻辑能够使用更灵活更方便的方法,避免了Powershell的 `ConstrainedLanguage` 模式.

### 配置 Python 依赖性

`node-gyp` 需要您安装一个 [支持的 Python 版本](https://devguide.python.org/versions/)。 。 。 . 如果您安装了多个版本的 Python , 您可以确定哪个版本 `node-gyp` 应以下列方式之一使用:

1.  通过设置 `--python` 命令行选项,例如:

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

2.  若为 `node-gyp` 被调用的方式 `npm`, (中文(简体) ), _财务报告和审定财务报表_ 您拥有多个版本 Python 已安装,然后可以设置 `npm_config_python` 环境变量 路径:

```bash
export npm_config_python=/path/to/executable/python
```

    或在窗口上 :

```console
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 搜索路径。 如果没有兼容的版本,就不再 搜索将完成 .
    

### 为第三方建立节点。 运行时

当为第三方节点(electron)等运行时 不同的构建配置与正式的节点.js发行,您 应使用 `--dist-url` 或者说 `--nodedir` 要指定标题的旗帜 运行时间来构建.

还有什么时候 `--dist-url` 或者说 `--nodedir` 标记通过,节点 -gyp将使用 `config.gypi` 在信头分发中运出以生成构建 配置,它不同于使用默认模式 `process.config` 对象.

一些旧版本的 Electron 运出错误 `config.gypi` 在标题中 分发,你可能需要通过 `--force-process-config` 到节点吉普 用于围绕配置错误工作.

## 如何使用

要编译您的本地加通, 请先到其根目录 :

```bash
cd my_node_addon
```

下一步是为当前生成适当的项目构建文件 平台。 使用 `configure` 为此:

```bash
node-gyp configure
```

Visual C++ 构建工具 2015 自动检测失败, 因此 `--msvs_version=2015` 需要添加( npm 运行时不需要如上配置) :

```bash
node-gyp configure --msvs_version=2015
```

**说明**编号: `configure` 步骤寻找 `binding.gyp` 当前文件 要处理的目录。 关于创建一个 `binding.gyp` 文档.

现在,你会有一个 `Makefile` (在Unix平台上)或 a `vcxproj` 文件 (在窗口上) `build/` 目录。 接下来,援引 `build` 命令 :

```bash
node-gyp build
```

现在你有你的编译 `.node` 装订文件! 编译的装订结束 内 `build/Debug/` 或者说 `build/Release/`,取决于构建模式。 现在, 您可以要求 : `.node` 和Node.js一起进行测试!

**说明:** 创建 _调试_ 构建绑定文件,通过 `--debug` (或 `-d`) 运行时切换 `configure`, (中文(简体) ), `build` 或者说 `rebuild` 命令.

## 这个 `binding.gyp` 文件

A 类 `binding.gyp` 文件描述构建模块的配置, 以 类似JSON的格式. 此文件会放在您的软件包的根中, 同时 `package.json`。 。 。 .

一条赤骨 `gyp` 适合构建节点.js addon的文件可能看起来像:

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

## 进一步阅读

这个 **[文档](https://npmcn.com/package/%40electron/node-gyp/docs/)** 目录中包含关于特定节点-gyp主题的额外文档,如果您在安装或使用节点-gyp构建添加符时遇到问题,这些文档可能有用.

为Node.js本地添加和写作提供一些额外资源 `gyp` 配置文件 :

-   ["去土著"节点学校.io 教程](http://nodeschool.io/#goingnative)
-   ["Hello World"节点附加示例](https://github.com/nodejs/node/tree/main/test/addons/hello-world)
-   [gyp 用户文档](https://gyp.gsrc.io/docs/UserDocumentation.md)
-   [gyp 输入格式参考](https://gyp.gsrc.io/docs/InputFormatReference.md)
-   [_"捆绑.gyp"在野外的文件_ 维基页面](https://npmcn.com/package/%40electron/node-gyp/docs/binding.gyp-files-in-the-wild.md)

## 图标

`node-gyp` 响应以下命令:

| **命令** | **说明** |
| :-- | :-- |
| `help` | 显示帮助对话框 |
| `build` | 调用 `make`编号 :`msbuild.exe` 并建造土生土长的加人 |
| `clean` | 删除 `build` 如果存在目录 |
| `configure` | 生成当前平台的项目构建文件 |
| `rebuild` | 运行 `clean`, (中文(简体) ), `configure` 财务报告和审定财务报表 `build` 全部排成一行 |
| `install` | 安装给定版本的 Node.js 头文件 |
| `list` | 列出目前安装的节点.js头版本 |
| `remove` | 删除给定版本的节点.js头文件 |

## 命令选项

`node-gyp` 接受下列命令选项:

| **命令** | **说明** |
| :-- | :-- |
| `-j n`, (中文(简体) ), `--jobs n` | 运行 `make` 平行进行。 数值 `max` 将使用所有可用的 CPU 核心 |
| `--target=v6.2.1` | 要构建的节点.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` | 从本地的柏球取信头 |
| `--devdir=$path` | SDK 下载目录( 默认为 OS 缓存目录) |
| `--ensure` | 如果已经存在, 不要重新安装信头 |
| `--dist-url=$url` | 从自定义 URL 下载信头 tarball |
| `--proxy=$url` | 设置 HTTP( S) 代理下载信头 tarball |
| `--noproxy=$urls` | 设定在下载信头 tarball 时忽略代理 |
| `--cafile=$cafile` | 覆盖默认 CA 链( 下载 tarball) |
| `--nodedir=$path` | 设置节点源代码的路径 |
| `--python=$path` | 设置 Python 二进制的路径 |
| `--msvs_version=$version` | 设置 Visual Studio 版本( 仅窗口) |
| `--solution=$solution` | 设置 Visual Studio 解决方案版本( 只有窗口) |
| `--force-process-config` | 使用运行时间强制 `process.config` 生成对象 `config.gypi` 文件 |

## 配置

### 环境变量

使用窗体 `npm_config_OPTION_NAME` 用于列出的任何命令选项 以上(选项名称中的标注应改为下划线).

例如,设置 `devdir` 等于 `/tmp/.gyp`你会:

在 Unix 上运行 :

```bash
export npm_config_devdir=/tmp/.gyp
```

或者这个在Windows上:

```console
set npm_config_devdir=c:\temp\.gyp
```

### `npm` v9 之前 npm 版本的配置

使用窗体 `OPTION_NAME` 用于上述任何命令选项.

例如,设置 `devdir` 等于 `/tmp/.gyp`你会跑:

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

**说明:** 配置设置通过 `npm` 将仅在 `node-gyp` 运行通过 `npm`,而不是当 `node-gyp` 直接运行.

## 许可证

`node-gyp` 以麻省理工学院的许可证提供。 见 [自由主义 文件](https://npmcn.com/package/%40electron/node-gyp/LICENSE) 详细情况.

## 常见问题

### @electron/node-gyp 是什么？

节点\.js 本地添加构建工具

### 如何安装 @electron/node-gyp？

在项目目录运行 npm install @electron/node-gyp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 node-gyp，可以用 npx node-gyp 直接运行。

### @electron/node-gyp 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/electron\_\_node-gyp 是否存在。

### @electron/node-gyp 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @electron/node-gyp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=12\.13\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @electron/node-gyp 可以商用吗？

@electron/node-gyp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @electron/node-gyp 的下载量有多少？

根据 npm 官方下载统计，@electron/node-gyp 在 2026/10/14 – 2026/11/12 这 30 天内被下载 1,577,077 次，日均约 52,569 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @electron/node-gyp 还在维护吗？

最新版本 10\.2\.0-electron\.2 发布于 2024/10/09（2 年前）；至今共发布 3 个版本，其中过去 12 个月发布了 0 个；首次发布于 2024/09/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。