文章目录
-
- [npm 安装 canvas 报错 node-gyp ERR](#npm 安装 canvas 报错 node-gyp ERR)
- [Build Tools for Visual Studio 2022 如何下载](#Build Tools for Visual Studio 2022 如何下载)
- [安装Visual Studio Build Tools后任然报错](#安装Visual Studio Build Tools后任然报错)
-
- [方案1：配置镜像源 + 跳过编译](#方案1：配置镜像源 + 跳过编译)
- [方案2：使用 MSYS2 安装 GTK（推荐）](#方案2：使用 MSYS2 安装 GTK（推荐）)
- [方案3：手动下载 GTK 完整包](#方案3：手动下载 GTK 完整包)
npm 安装 canvas 报错 node-gyp ERR
遇到的问题：
在使用 npm install 安装依赖时，很多朋友都会遇到类似这样的错误：
npm ERR! gyp ERR! build error
npm ERR! node-pre-gyp ERR! build error
npm ERR! Failed to execute 'node-gyp configure ...'如下图：
尤其是当项目 中包含 canvas 模块时，这种错误出现得非常频繁。
本文分享两种在 Windows 环境 下最常用的解决方式，第二种为推荐方案。
问题分析
canvas 模块是一个基于 C++ 实现的 Node.js 图形绘图库，在安装时需要进行 C++ 原生扩展编译，而 Node.js 的包管理器（npm）会调用 node-gyp 去执行编译操作。在 Windows 下，如果没有安装 Visual Studio 编译环境，就会导致编译失败，从而报出：
npm ERR! gyp ERR! build error
npm ERR! node-pre-gyp ERR! not ok解决方案1：使用 windows-build-tools（简易方案）
适用于 Node.js v16 及以下版本，一条命令自动搞定所需环境。
步骤如下：
1、以管理员身份运行 PowerShell（必须是管理员，否则会报权限错误）
2、执行命令：npm install --global --production windows-build-tools
3、等待安装完成（会自动安装 Python 和 C++ 构建工具）
过程可能需要几分钟。
4、再重新执行：npm install
如果顺利完成，说明环境已配置成功。
不过这个方案在新版 Node.js（v18、v20）上已经 不推荐使用，因此更稳定的方法是手动安装 Visual Studio 构建工具。
解决方案2：手动安装 Visual Studio Build Tools（推荐）
这是 最稳定、官方推荐 的方式，适用于所有 Node.js 版本。
如果你要长期开发、编译原生模块（例如 canvas、bcrypt、sharp 等），建议使用这一方法。
- 下载 并安装 Visual Studio Build Tools
前往微软官方下载页面：https://visualstudio.microsoft.com/visual-cpp-build-tools/
下载 "Build Tools for Visual Studio 2022" 安装包。
- 选择组件
安装时，在安装界面左侧选择：使用 C++ 的桌面开发（Desktop development with C++）
右侧勾选以下组件：
- MSVC v143 - VS 2022 C++ 编译器和库
- Windows 10 SDK 或 Windows 11 SDK
- C++ CMake 工具（可选）
- 安装完成后
安装完成后，重新启动电脑 或重新打开命令行窗口，确保环境变量生效。
- 安装 canvas 模块：
在项目根目录执行：npm install canvas@2.11.2
如果之前安装失败过，可以先清除缓存：
# 清除npm下载的缓存
npm cache clean --force
# 删除node_modules目录
#rimraf node_modules
# 直接安装最新版本
npm install canvas@latest为什么推荐第二种方式？
第二种（手动安装 Build Tools）方案虽然步骤多一点，但：
✅ 稳定性更好 ------ 不受 Node 版本限制
✅ 官方支持 ------ 与 node-gyp 完全兼容
✅ 一劳永逸 ------ 以后安装其他 C++ 扩展模块也不会再报错
而第一种方案 windows-build-tools 已经不再维护，对 Node.js 18+ 兼容性较差。
附加提示：纯前端项目是否需要 canvas？
如果你只是运行一个 Vue 项目，并没有手动用到 canvas（例如生成图片、二维码、图表等），
可以直接跳过这个模块安装，比如执行：npm install canvas@2.11.2 --ignore-scripts
这样可以避免 node-gyp 编译，快速完成安装。
总结：
canvas 报 node-gyp 错，是因为缺少 C++ 编译环境。
安装 Visual Studio Build Tools，一次解决所有编译型 npm 包的问题。
Build Tools for Visual Studio 2022 如何下载
地址：https://my.visualstudio.com/Downloads?q=Visual Studio 2022
地址2：https://visualstudio.microsoft.com/zh-hans/visual-cpp-build-tools/
https://visualstudio.microsoft.com/zh-hans/vs/older-downloads/
安装Visual Studio Build Tools后任然报错
这个错误信息非常关键！它明确告诉我们：编译环境已经就绪（VS2022已找到），但缺少 canvas 的核心依赖库 cairo.h。
这是因为 canvas 在 Windows 上需要依赖 GTK 或其他第三方库，这些库不会随 Visual Studio 自动安装。现在你只需要手动提供这些依赖库即可。
🎯 最直接的解决方案：使用预编译二进制文件
既然你已经有了 VS2022 Build Tools，最省事的方式是强制使用预编译版本，完全跳过本地编译：
方案1：配置镜像源 + 跳过编译
bash
# 1. 清理缓存和旧文件
npm cache clean --force
rmdir /s node_modules 2>nul
del package-lock.json 2>nul
# 2. 设置环境变量，强制下载预编译文件
# 环境变量 set 命令设置的是临时变量，只对当前命令行窗口有效
# 如果你想在当前窗口立即取消这个变量，可以将其设为空值：set canvas_binary_host_mirror=
# 如果你用 setx 命令设置了永久环境变量，需要用 setx canvas_binary_host_mirror "" 来删除
set canvas_binary_host_mirror=https://registry.npmmirror.com/-/binary/canvas
set npm_config_canvas_binary_host_mirror=https://registry.npmmirror.com/-/binary/canvas
# 查看所有环境变量中是否还有 canvas_binary_host_mirror
set | findstr canvas
# 3. 安装 canvas（会优先下载 .node 文件）
npm install canvas@latest
# 设置 npm 全局配置
npm config set timeout 600000
npm config set fetch-retry-mintimeout 20000
npm config set fetch-retry-maxtimeout 120000如果 npm 下载一直超时，可以试试 cnpm：
bash
# 使用淘宝 npm 镜像
# npm config set registry https://registry.npmmirror.com
# 安装 cnpm
npm install -g cnpm --registry=https://registry.npmmirror.com
# 使用 cnpm 安装（它默认使用镜像，且超时时间更长）
cnpm install canvas@latest方案2：使用 MSYS2 安装 GTK（推荐）
MSYS2 是 Windows 上最流行的 Unix 工具链和库提供者，比 gvsbuild 更稳定。
-
安装 MSYS2
- 下载安装包：
https://www.msys2.org/ - 运行安装程序，建议安装在
C:\msys64 - 安装完成后，运行 "MSYS2 MSYS" 终端
- 下载安装包：
-
在 MSYS2 中安装 GTK 开发库
在 MSYS2 终端中依次执行：
bash
# 更新包数据库
pacman -Syu
# 如果提示关闭终端，就关闭重新打开，再执行一次
pacman -Syu
# 安装完整的 GTK3 开发包（包含所有依赖）
pacman -S mingw-w64-x86_64-gtk3
# 单独确认这些关键库已安装
pacman -S mingw-w64-x86_64-cairo mingw-w64-x86_64-pango mingw-w64-x86_64-librsvg mingw-w64-x86_64-libpng mingw-w64-x86_64-giflib mingw-w64-x86_64-jpeg-turbo mingw-w64-ucrt-x86_64-libjpeg-turbo- 配置环境变量
-
按
Win + R，输入sysdm.cpl，进入"高级"→"环境变量" -
在系统变量中：
- 编辑
Path，添加C:\msys64\mingw64\bin - 新建
INCLUDE，值为C:\msys64\mingw64\include - 新建
LIB，值为C:\msys64\mingw64\lib - 新建
PKG_CONFIG_PATH，值为C:\msys64\mingw64\lib\pkgconfig
- 编辑
-
重启命令行终端使环境变量生效
-
重启命令行终端，然后验证：
bash
# 检查头文件是否存在
dir C:\msys64\mingw64\include\cairo.h
# 检查库文件是否存在
dir C:\msys64\mingw64\lib\libcairo.a
# 检查 pkg-config 是否能找到 cairo
pkg-config --cflags cairo-
安装 canvas
bashnpm install canvas@latest
方案3：手动下载 GTK 完整包
如果 MSYS2 安装太慢，可以从这里下载预编译包：
- 下载 GTK 的 Windows 版本：
https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases - 安装到
C:\gtk - 配置环境变量：
Path添加C:\gtk\bin- 新建
INCLUDE为C:\gtk\include - 新建
LIB为C:\gtk\lib
为什么没有 include 目录？
预编译的 GTK 包通常分为两种：
- 运行时（Runtime）包：只包含 bin、etc、share 等目录，用于运行已有的 GTK 程序。
- 开发包（Dev/Devel 包）：包含 include、lib、lib/pkgconfig 等目录，供开发者编译程序使用。
你安装的版本缺少 include 目录，说明它属于前者，如果缺少include 目录，不能解决该问题。
参考：https://blog.csdn.net/m0_73457571/article/details/153831434
https://blog.csdn.net/weixin_44200553/article/details/158849470