npm 安装 canvas 报错 node-gyp ERR! 的解决方法（Windows 系统）
一、遇到的问题：
在使用 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
三、解决方案一：使用 windows-build-tools（简易方案）
适用于 Node.js v16 及以下版本，一条命令自动搞定所需环境。
步骤如下：
以管理员身份运行 PowerShell
（必须是管理员，否则会报权限错误）执行命令：npm install --global --production windows-build-tools
等待安装完成（会自动安装 Python 和 C++ 构建工具）
过程可能需要几分钟。再重新执行：npm install
如果顺利完成，说明环境已配置成功。
不过这个方案在新版 Node.js（v18、v20）上已经 不推荐使用，因此更稳定的方法是手动安装 Visual Studio 构建工具。
四、解决方案二：手动安装 Visual Studio Build Tools（推荐）
这是 最稳定、官方推荐 的方式，适用于所有 Node.js 版本。
如果你要长期开发、编译原生模块（例如 canvas、bcrypt、sharp 等），建议使用这一方法。
1. 下载并安装 Visual Studio Build Tools
前往微软官方下载页面：
👉 https://visualstudio.microsoft.com/visual-cpp-build-tools/
下载 “Build Tools for Visual Studio 2022” 安装包。
2. 选择组件
安装时，在安装界面左侧选择：
使用 C++ 的桌面开发（Desktop development with C++）
右侧勾选以下组件：
MSVC v143 - VS 2022 C++ 编译器和库
Windows 10 SDK 或 Windows 11 SDK
C++ CMake 工具（可选）
3. 安装完成后
安装完成后，重新启动电脑 或重新打开命令行窗口，确保环境变量生效。
4. 安装 canvas 模块：
在项目根目录执行：npm install canvas@2.11.2
如果之前安装失败过，可以先清除缓存：
npm cache clean --force
rimraf node_modules
npm install
四、为什么推荐第二种方式？
第二种（手动安装 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 包的问题。