在公司内网环境下,通过 npm install 命令安装涉及 C++ 代码的二进制依赖时,经常会遭遇 node-gyp 编译报错的问题,从而导致依赖安装失败,阻塞后续开发。
这种问题在 Windows 上尤为常见,而在 Mac 和 Linux 上较为罕见。主要原因是许多 Node.js 原生模块在 Mac 和 Linux 下通常使用 GCC 或 Clang 工具链,而在 Windows 下的编译环境相对复杂,一般使用 Visual Studio 的工具链,需要安装完整的集成开发环境。
本文将深入探讨开发人员在公司内网 Windows 机器上执行 npm install 时,如何处理与 node-gyp 相关的报错问题。
理解问题
什么是 node-gyp?
Node-gyp 是一个 Node.js 工具,专用于编译 Node.js 插件。这些插件通常是使用 C++ 编写的,需要编译成本地二进制文件才能在 Node.js 环境中运行。
这是因为在安装这类包含 C++ 代码的 Node.js 模块时,Node.js 包管理器 npm 会检查系统是否具备必要的构建工具和依赖项,如果没有,它将试图下载并安装这些构建工具,然后使用它们编译 C++ 模块的源代码。而在公司内网环境下(即网络隔离),因为无法直接通过 Internet 下载这些必要的构建工具,所以就会导致 node-gyp 相关编译错误。
因此,在安装包含 C++ 代码的 Node.js 模块时,我们需要确保当前系统已安装了适当的构建工具和依赖项。在 Windows 系统上,可能需要安装 Visual Studio 工具链或其他适用的编译工具。
常见问题
在使用 node-gyp 构建 Node.js 原生 C++ 模块时,由于操作系统的多样性和复杂性,遇到的报错类型也是比较多样的。
npm ERR! gyp ERR! find Python - Set the npm configuration variable python: npm ERR! gyp ERR! find Python npm config set python "C:\Path\To\python.exx" npm ERR! gyp ERR! find Python For more information consult the documentation at: npm ERR! gyp ERR! find Python https://github.com/nodejs/node-gyp#installation npm ERR! gyp ERR! find Python **************************************************** npm ERR! gyp ERR! find Python npm ERR! gyp ERR! configure error npm ERR! gyp ERR! stack Error: Could not find any Python installation to use npm ERR! gyp ERR! stack at PythonFinder.fail (C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\lib\find-python.js:330:47) npm ERR! gyp ERR! stack at PythonFinder.runChecks (C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\lib\find-python.js:159:21) npm ERR! gyp ERR! stack at PythonFinder.<anonymous> (C:\Program File\nodejs\node_modules\npm\node_modules\node-gyp\lib\find-python.js:228:18) npm ERR! gyp ERR! stack at PythonFinder.execFileCallback (C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\lib\find-pyhon.js:294:16) npm ERR! gyp ERR! stack at exithandler (node:child_process:404:5) npm ERR! gyp ERR! stack at ChildProcess.errorhandler (node:child_process:416:5) npm ERR! gyp ERR! stack at ChildProcess.emit (node:events:390:28) npm ERR! gyp ERR! stack at Process.ChildProcess._handle.onexit (node:internal/child_process:288:12) npm ERR! gyp ERR! stack at onErrorNT (node:internal/child_process:477:16) npm ERR! gyp ERR! stack at processTicksAndRejections (node:internal/process/task_queues:83:21) npm ERR! gyp ERR! System Windows_NT 10.0.14393 npm ERR! gyp ERR! command"C:\\Program Files\\nodejs\\node.exe""C:\\Program Files\\nodejs\\node_modules\\npm\\node_modules\\node-gyp\\bin\\node-gyp.js""rebuild" npm ERR! gyp ERR! cwd C:\Users\jcadmin\Desktop\work\node_modules\bufferutil npm ERR! gyp ERR! node -v v16.13.1 npm ERR! gyp ERR! node-gyp -v v8.3.0 npm ERR! gyp ERR! not ok
分析 npm ERR! gyp ERR! stack Error: Could not find any Python installation to use 可知是缺少 python 环境,我们需要根据当前机器的 Windows 版本(64 位还是 32 位)从 Python 的官方网站下载 Python 3.12 对应的安装程序,然后,运行下载的 exe 安装包:
特别要注意勾上Add Python 3.x to PATH,然后点 Install Now 即可完成安装。
npm ERR! code 1 npm ERR! path C:\Users\jsadmin\Desktop\work\node_modules\bufferutil npm ERR! command failed npm ERR! command C:\windows\system32\cmd.exe /d /s /c node-gyp rebuild npm ERR! gyp info it worked if it ends with ok npm ERR! gyp info using node-gyp@8.3.0 npm ERR! gyp info using node@16.13.1 | win32 | x64 npm ERR! gyp info find Python using Python version 3.11.4 found at "C:\Users\jsadmin\AppData\Local\Programs\Python\Python311\python.exe" npm ERR! gyp ERR! find VS npm ERR! gyp ERR! find VS msvs_version not set from command line or npm config npm ERR! gyp ERR! find VS VCINSTALLDIR not set, not running in VS Command Prompt npm ERR! gyp ERR! find VS could not use PowerShell to find Visual Studio 2017 or newer, try re-running with '--loglevel silly'for more details npm ERR! gyp ERR! find VS looking for Visual Studio 2015 npm ERR! gyp ERR! find VS - not found npm ERR! gyp ERR! find VS not looking for VS2013 as it is only supported up to Node.js 8 npm ERR! gyp ERR! find VS npm ERR! gyp ERR! find VS *************************************************************** npm ERR! gyp ERR! find VS You need to install the latest version of Visual Studio npm ERR! gyp ERR! find VS including the "Desktop development with C++" workload. npm ERR! gyp ERR! find VS For more information consult the documentation at: npm ERR! gyp ERR! find VS https://github.com/nodejs/node-gyp#on-windows npm ERR! gyp ERR! find VS *************************************************************** npm ERR! gyp ERR! find VS npm ERR! gyp ERR! configure error npm ERR! gyp ERR! stack Error: Could not find any Visual Studio installation to use npm ERR! gyp ERR! stack at VisualStudioFinder.fail (C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\lib\find-visualstudio.js:121:47) npm ERR! gyp ERR! stack at C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\lib\find-visualstudio.js:74:16 npm ERR! gyp ERR! stack at VisualStudioFinder.findVisualStudio2013 (C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\lib\find-visualstudio.js:351:14) npm ERR! gyp ERR! stack at C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\lib\find-visualstudio.js:70:14 npm ERR! gyp ERR! stack at C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\lib\find-visualstudio.js:372:16 npm ERR! gyp ERR! stack at C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\lib\util.js:54:7 npm ERR! gyp ERR! stack at C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\lib\util.js:33:16 npm ERR! gyp ERR! stack at ChildProcess.exithandler (node:child_process:404:5) npm ERR! gyp ERR! stack at ChildProcess.emit (node:events:390:28) npm ERR! gyp ERR! stack at maybeClose (node:internal/child_process:1064:16) npm ERR! gyp ERR! System Windows_NT 10.0.14393 npm ERR! gyp ERR! command"C:\\Program Files\\nodejs\\node.exe""C:\\Program Files\\nodejs\\node_modules\\npm\\node_modules\\node-gyp\\bin\\node-gyp.js""rebuild" npm ERR! gyp ERR! cwd C:\Users\jsadmin\Desktop\work\node_modules\bufferutil npm ERR! gyp ERR! node -v v16.13.1 npm ERR! gyp ERR! node-gyp -v v8.3.0 npm ERR! gyp ERR! not ok
分析报错信息 npm ERR! gyp ERR! stack Error: Could not find any Visual Studio installation to use 可知,主要是缺少了 Visual Studio,也就是缺少了 node-gyp 所要求的 C++ 编译环境。
下面将简要介绍如何安装 C++ 编译环境:
在线安装
在公司内网环境搭建初期,可能需要通过 Internet 网络来下载一些必要配置。如果安全限制较高,也可以通过临时开通网络白名单得方式,从而通过网络进行环境搭建。(离线部署在后续章节说明)
首先,我们需要在 Internet 网络环境下,下载指定版本的 vs_BuildTools.exe 文件(这里以 2019 为例),它是 Microsoft Visual Studio Build Tools 的安装程序,是 Microsoft Visual Studio 的一个轻量级版本,专门用于提供编译和构建工具,而不包含完整的 Visual Studio IDE,可通过以下官网链接获取:Visual Studio Build Tools。
接着在目标机器上执行以下步骤:
将下载好的 vs_BuildTools.exe 文件传输到目标机器。
在目标机器上双击运行 vs_BuildTools.exe 文件,开始安装 Visual Studio Build Tools 内容。
在 Visual Studio Installer 中,选择「使用 C++的桌面开发」工作负荷(以 Community 2019 版本为例)。
1、打开命令提示符,导航到要下载引导程序的目录,使用 Visual Studio 页中定义的引导程序参数来创建和维护网络布局。
2、对于 Visual Studio Community,单一语言区域设置的完整初始布局需要约 40 GB 的磁盘空间,而 Visual Studio Enterprise 则需要约 50 GB 的磁盘空间。 其他每个语言区域设置需要大约 0.5 GB 的磁盘空间。
推荐的方法是使用所有工作负载和适当的语言创建 Visual Studio 的初始布局,并将包存储到网络服务器上的布局目录中。 这样,任何客户端安装都有权访问整个 Visual Studio 产品/服务,并能够安装任何子集。若要创建 Visual Studio 的完整布局,请从你计划用于托管网络布局的目录运行以下命令: