mac安装canvas依赖报错主因是arm64/x86_64架构不匹配，须用arm64原生node（nvm install --lts --arch=arm64）、homebrew装cairo等依赖、配置pkg_config_path/ldflags/cppflags环境变量，再npm install canvas --build-from-source。
Mac系统安装Node.js的canvas依赖时频繁报错，常见于node-gyp编译失败、jpeglib.h找不到、pkg-config路径失效或arm64/x86_64架构不匹配，直接导致项目无法启动或require时报Cannot find module '../build/Release/canvas.node'。
确认你的Mac芯片架构
打开终端，执行：
uname -m
如果输出是【arm64】（M1/M2/M3芯片），但你装的是x86_64版Node.js，后续所有编译都会失败——Rosetta转译无法生成原生canvas.node文件。必须用arm64原生Node版本。
验证Node架构：node -p "process.arch"，结果也必须是arm64。
重装arm64原生Node.js（推荐使用nvm）
方法一：用nvm安装arm64专用Node版本
先卸载旧Node（如通过pkg安装的）：sudo rm -rf /usr/local/{bin/{node,npm},lib/node_modules/npm,lib/node,share/man/man1/node.1}
安装nvm：curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
重启终端后执行：
nvm install --lts --arch=arm64 → nvm use --lts
这一步必须指定--arch=arm64，否则nvm默认可能拉x86_64二进制包，尤其在已启用Rosetta的终端里极易踩坑。
安装系统级图形依赖库
方法1：用Homebrew一键安装（最简）
确保已安装Xcode命令行工具：xcode-select --install
执行：
brew install pkg-config cairo pango libpng jpeg giflib librsvg
注意：不要用brew install cairo --with-x11，macOS 12+已弃用X11支持，加该参数会导致configure失败。
方法2：手动验证pkg-config是否生效
pkg-config --modversion cairo
若报command not found，说明brew安装未写入PATH，检查~/.zshrc中是否有export PATH="/opt/homebrew/bin:$PATH"（Apple Silicon）或export PATH="/usr/local/bin:$PATH"（Intel），缺则补上并source ~/.zshrc。
配置canvas安装环境变量
执行以下三行命令（顺序不可颠倒）：
export PKG_CONFIG_PATH="/opt/homebrew/lib/pkgconfig:$PKG_CONFIG_PATH"
export LDFLAGS="-L/opt/homebrew/lib"
export CPPFLAGS="-I/opt/homebrew/include"
将这三行永久写入~/.zshrc（Apple Silicon）或~/.zshrc（Intel用户对应改/opt/homebrew为/usr/local），否则每次新开终端都要重设。
【关键前提】这三行必须在npm install canvas前生效，否则canvas configure阶段根本找不到cairo和jpeg头文件。
安装canvas并验证
第一步：清除残留构建缓存
rm -rf node_modules/canvas && npm cache clean --force
第二步：指定镜像加速安装（国内用户必做）
npm install canvas --canvas_binary_host_mirror=https://registry.npmmirror.com/-/binary/canvas
第三步：若仍编译失败，强制源码构建
npm install canvas --build-from-source --unsafe-perm
安装完成后，在项目里运行node -e "require('canvas')"`，无报错即成功。
