Windows环境npm install安装canvas@2.8.0报错编译失败问题求助

AI 小北

2026-9-24

原始报错日志

npm WARN old lockfile
npm WARN old lockfile package-lock.json文件由旧版本npm创建，因此需要从registry拉取补充元数据。
npm WARN old lockfile
npm WARN old lockfile 这是一次性修复操作，请耐心等待...
npm WARN old lockfile
npm ERR! code 1
npm ERR! path D:\nft\hashlips_art_engine-1.1.2_update\node_modules\canvas
npm ERR! command failed
npm ERR! command C:\Windows\system32\cmd.exe /d /s /c node-pre-gyp install --fallback-to-build
npm ERR! 执行命令 'C:\Program Files\nodejs\node.exe C:\Users\User\AppData\Roaming\npm\node_modules\npm\node_modules\node-gyp\bin\node-gyp.js configure --fallback-to-build --module=D:\nft\hashlips_art_engine-1.1.2_update\node_modules\canvas\build\Release\canvas.node --module_name=canvas --module_path=D:\nft\hashlips_art_engine-1.1.2_update\node_modules\canvas\build\Release --napi_version=8 --node_abi_napi=napi --napi_build_version=0 --node_napi_label=node-v102 --python=python2.7 --msvs_version=2017' 失败，错误码1
npm ERR! node-pre-gyp info 若运行结束输出ok则表示执行成功
npm ERR! node-pre-gyp info 当前使用版本 node-pre-gyp@1.0.6
npm ERR! node-pre-gyp info 当前运行环境 node@17.1.0 | win32 | x64
npm ERR! node-pre-gyp info 检查路径 "D:\nft\hashlips_art_engine-1.1.2_update\node_modules\canvas\build\Release\canvas.node" 不存在
npm ERR! node-pre-gyp http GET https://github.com/Automattic/node-canvas/releases/download/v2.8.0/canvas-v2.8.0-node-v102-win32-unknown-x64.tar.gz
npm ERR! node-pre-gyp ERR! install 访问上述地址返回状态码 404 Not Found
npm ERR! node-pre-gyp WARN canvas@2.8.0 与 node@17.1.0 (node-v102 ABI, unknown) 无匹配预编译二进制包，将通过 node-gyp fallback到源码编译
npm ERR! node-pre-gyp WARN 触发错误原因：上述预编译包地址返回404
npm ERR! gyp info 若运行结束输出ok则表示执行成功
npm ERR! gyp info 当前使用版本 node-gyp@8.4.0
npm ERR! gyp info 当前运行环境 node@17.1.0 | win32 | x64
npm ERR! gyp info ok
npm ERR! gyp info 若运行结束输出ok则表示执行成功
npm ERR! gyp info 当前使用版本 node-gyp@8.4.0
npm ERR! gyp info 当前运行环境 node@17.1.0 | win32 | x64
npm ERR! gyp info 找到Python版本 3.10.0，路径为 "C:\Python310\python.exe"
npm ERR! gyp ERR! find VS
npm ERR! gyp ERR! find VS msvs_version已通过命令行或npm配置指定
npm ERR! gyp ERR! find VS - 正在查找Visual Studio 2017版本
npm ERR! gyp ERR! find VS 未设置VCINSTALLDIR变量，未在VS命令提示符中运行
npm ERR! gyp ERR! find VS 检测到VS2019 (16.11.31911.196)，路径为：
npm ERR! gyp ERR! find VS "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools"
npm ERR! gyp ERR! find VS - 已找到 "Visual Studio C++ core features"
npm ERR! gyp ERR! find VS - 缺失VC工具集
npm ERR! gyp ERR! find VS 找不到可使用的Visual Studio 2017或更新版本
npm ERR! gyp ERR! find VS 正在查找Visual Studio 2015
npm ERR! gyp ERR! find VS - 未找到
npm ERR! gyp ERR! find VS 无需查找VS2013，仅Node.js 8及更早版本支持该版本
npm ERR! gyp ERR! find VS
npm ERR! gyp ERR! find VS msvs_version可用版本：
npm ERR! gyp ERR! find VS
npm ERR! gyp ERR! find VS **************************************************************
npm ERR! gyp ERR! find VS 你需要安装最新版Visual Studio，且勾选 "Desktop development with C" 工作负载。
npm ERR! gyp ERR! find VS 更多信息可参考文档：
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: 找不到可用的Visual Studio安装
npm ERR! gyp ERR! stack at VisualStudioFinder.fail (C:\Users\User\AppData\Roaming\npm\node_modules\npm\node_modules\node-gyp\lib\find-visualstudio.js:122:47)
npm ERR! gyp ERR! stack at C:\Users\User\AppData\Roaming\npm\node_modules\npm\node_modules\node-gyp\lib\find-visualstudio.js:75:16
npm ERR! gyp ERR! stack at VisualStudioFinder.findVisualStudio2013 (C:\Users\User\AppData\Roaming\npm\node_modules\npm\node_modules\node-gyp\lib\find-visualstudio.js:363:14)
npm ERR! gyp ERR! stack at C:\Users\User\AppData\Roaming\npm\node_modules\npm\node_modules\node-gyp\lib\find-visualstudio.js:71:14
npm ERR! gyp ERR! stack at C:\Users\User\AppData\Roaming\npm\node_modules\npm\node_modules\node-gyp\lib\find-visualstudio.js:384:16
npm ERR! gyp ERR! stack at C:\Users\User\AppData\Roaming\npm\node_modules\npm\node_modules\node-gyp\lib\util.js:54:7
npm ERR! gyp ERR! stack at C:\Users\User\AppData\Roaming\npm\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:1062:16)
npm ERR! gyp ERR! System Windows_NT 10.0.10240
npm ERR! gyp ERR! command "C:\Program Files\nodejs\node.exe" "C:\Users\User\AppData\Roaming\npm\node_modules\npm\node_modules\node-gyp\bin\node-gyp.js" "configure" "--fallback-to-build" "--module=D:\nft\hashlips_art_engine-1.1.2_update\node_modules\canvas\build\Release\canvas.node" "--module_name=canvas" "--module_path=D:\nft\hashlips_art_engine-1.1.2_update\node_modules\canvas\build\Release" "--napi_version=8" "--node_abi_napi=napi" "--napi_build_version=0" "--node_napi_label=node-v102" "--python=python2.7" "--msvs_version=2017"
npm ERR! gyp ERR! cwd D:\nft\hashlips_art_engine-1.1.2_update\node_modules\canvas
npm ERR! gyp ERR! node -v v17.1.0
npm ERR! gyp ERR! node-gyp -v v8.4.0
npm ERR! gyp ERR! not ok
npm ERR! node-pre-gyp ERR! build error
npm ERR! node-pre-gyp ERR! stack Error: 执行命令 'C:\Program Files\nodejs\node.exe C:\Users\User\AppData\Roaming\npm\node_modules\npm\node_modules\node-gyp\bin\node-gyp.js configure --fallback-to-build --module=D:\nft\hashlips_art_engine-1.1.2_update\node_modules\canvas\build\Release\canvas.node --module_name=canvas --module_path=D:\nft\hashlips_art_engine-1.1.2_update\node_modules\canvas\build\Release --napi_version=8 --node_abi_napi=napi --napi_build_version=0 --node_napi_label=node-v102 --python=python2.7 --msvs_version=2017' 失败，错误码1
npm ERR! node-pre-gyp ERR! stack at ChildProcess. (D:\nft\hashlips_art_engine-1.1.2_update\node_modules@mapbox\node-pre-gyp\lib\util\compile.js:89:23)
npm ERR! node-pre-gyp ERR! stack at ChildProcess.emit (node:events:390:28)
npm ERR! node-pre-gyp ERR! stack at maybeClose (node:internal/child_process:1062:16)
npm ERR! node-pre-gyp ERR! stack at Process.ChildProcess._handle.onexit (node:internal/child_process:301:5)
npm ERR! node-pre-gyp ERR! System Windows_NT 10.0.10240
npm ERR! node-pre-gyp ERR! command "C:\Program Files\nodejs\node.exe" "D:\nft\hashlips_art_engine-1.1.2_update\node_modules@mapbox\node-pre-gyp\bin\node-pre-gyp" "install" "--fallback-to-build"
npm ERR! node-pre-gyp ERR! cwd D:\nft\hashlips_art_engine-1.1.2_update\node_modules\canvas
npm ERR! node-pre-gyp ERR! node -v v17.1.0
npm ERR! node-pre-gyp ERR! node-pre-gyp -v v1.0.6
npm ERR! node-pre-gyp ERR! not ok
npm ERR! 本次运行完整日志可在以下路径查看：
npm ERR! C:\Users\User\AppData\Local\npm-cache_logs\2021-11-10T15_29_35_648Z-debug.log

错误原因分析

核心问题出在canvas@2.8.0依赖安装失败：当前使用的Node.js 17.1.0属于非长期支持的迭代版本，canvas@2.8.0没有提供对应该版本的预编译二进制安装包，需要通过node-gyp在本地进行源码编译才能安装
本地编译环境不满足要求：已安装的Visual Studio 2019缺少VC++工具集，且npm全局配置指定的msvs编译版本为2017，和本地实际安装的VS版本不匹配，导致源码编译流程无法正常启动

解决办法

方案一（推荐，操作成本最低）
将当前Node.js 17.1.0降级到16.x LTS长期支持版本，canvas@2.8.0官方提供该Node版本对应的预编译包，无需本地编译。版本切换完成后，删除项目根目录下的node_modules文件夹、package-lock.json文件，重新执行npm install即可完成所有依赖安装。
方案二（保留当前Node.js 17.1.0版本）
1. 先清理本地无效缓存和残留文件：删除项目根目录下的node_modules文件夹、package-lock.json文件，执行命令npm cache clean --force
2. 打开Visual Studio Installer，选择已安装的Visual Studio 2019，点击修改按钮，勾选「使用C++的桌面开发」工作负载，等待组件安装完成后重启电脑
3. 执行命令npm config set msvs_version 2019，将npm的编译工具版本和本地实际安装的VS版本对齐
4. 回到项目根目录重新执行npm install即可

内容的提问来源于stack exchange，提问作者Goku