MacOS M2环境下NextJS 13项目安装node-canvas失败求助

核心原因 #

• canvas@2.11.2未提供适配Node.js 20（ABI v115）的ARM64预编译二进制包，触发源码编译流程
• 源码编译时，pkg-config无法找到brew安装的依赖配置文件（如zlib.pc、libffi.pc），导致头文件（如cairo.h）缺失

分步解决方案 #

1. 安装完整系统依赖 #

确保编译所需的所有依赖通过brew安装：

brew install pkg-config cairo pango libpng jpeg giflib librsvg pixman zlib libffi

2. 配置PKG_CONFIG_PATH环境变量 #

ARM64 macOS（M系列芯片）的brew默认安装路径为/opt/homebrew，需让pkg-config识别该路径下的配置文件：

export PKG_CONFIG_PATH="/opt/homebrew/lib/pkgconfig:/opt/homebrew/share/pkgconfig"

如果是Intel芯片，替换为：

export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:/usr/local/share/pkgconfig"

持久化配置：将上述命令添加到~/.zshrc或~/.bashrc文件末尾，重启终端后生效。

3. 清理缓存并重新安装 #

npm uninstall canvas
rm -rf node_modules package-lock.json
npm install canvas

备选方案：升级canvas到最新版本 #

canvas@2.12.0及以上版本已适配Node.js 20的ARM64预编译包，直接安装最新版可跳过源码编译：

npm install canvas@latest

报错信息参考 #

npm ERR! path /Users/user1/Projects/Raccord/webapp/node_modules/canvas
npm ERR! command failed
npm ERR! command sh -c node-pre-gyp install --fallback-to-build --update-binary
npm ERR! SOLINK_MODULE(target) Release/canvas-postbuild.node
npm ERR!   CXX(target) Release/obj.target/canvas/src/backend/Backend.o
npm ERR! Failed to execute '/Users/user1/.nvm/versions/node/v20.9.0/bin/node /Users/user1/.nvm/versions/node/v20.9.0/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js build --fallback-to-build --update-binary --module=/Users/user1/Projects/Raccord/webapp/node_modules/canvas/build/Release/canvas.node --module_name=canvas --module_path=/Users/user1/Projects/Raccord/webapp/node_modules/canvas/build/Release --napi_version=9 --node_abi_napi=napi --napi_build_version=0 --node_napi_label=node-v115' (1)
npm ERR! node-pre-gyp info it worked if it ends with ok
npm ERR! node-pre-gyp info using node-pre-gyp@1.0.11
npm ERR! node-pre-gyp info using node@20.9.0 | darwin | arm64
npm ERR! node-pre-gyp http GET https://github.com/Automattic/node-canvas/releases/download/v2.11.2/canvas-v2.11.2-node-v115-darwin-unknown-arm64.tar.gz
npm ERR! node-pre-gyp ERR! install response status 404 Not Found on https://github.com/Automattic/node-canvas/releases/download/v2.11.2/canvas-v2.11.2-node-v115-darwin-unknown-arm64.tar.gz 
npm ERR! node-pre-gyp WARN Pre-built binaries not installable for canvas@2.11.2 and node@20.9.0 (node-v115 ABI, unknown) (falling back to source compile with node-gyp) 
npm ERR! node-pre-gyp WARN Hit error response status 404 Not Found on https://github.com/Automattic/node-canvas/releases/download/v2.11.2/canvas-v2.11.2-node-v115-darwin-unknown-arm64.tar.gz 
npm ERR! gyp info it worked if it ends with ok
npm ERR! gyp info using node-gyp@9.4.0
npm ERR! gyp info using node@20.9.0 | darwin | arm64
npm ERR! gyp info ok 
npm ERR! gyp info it worked if it ends with ok
npm ERR! gyp info using node-gyp@9.4.0
npm ERR! gyp info using node@20.9.0 | darwin | arm64
npm ERR! gyp info find Python using Python version 3.9.6 found at "/Library/Developer/CommandLineTools/usr/bin/python3"
npm ERR! gyp info spawn /Library/Developer/CommandLineTools/usr/bin/python3
npm ERR! gyp info spawn args [
npm ERR! gyp info spawn args   '/Users/user1/.nvm/versions/node/v20.9.0/lib/node_modules/npm/node_modules/node-gyp/gyp/gyp_main.py',
npm ERR! gyp info spawn args   'binding.gyp',
npm ERR! gyp info spawn args   '-f',
npm ERR! gyp info spawn args   'make',
npm ERR! gyp info spawn args   '-I',
npm ERR! gyp info spawn args   '/Users/user1/Projects/Raccord/webapp/node_modules/canvas/build/config.gypi',
npm ERR! gyp info spawn args   '-I',
npm ERR! gyp info spawn args   '/Users/user1/.nvm/versions/node/v20.9.0/lib/node_modules/npm/node_modules/node-gyp/addon.gypi',
npm ERR! gyp info spawn args   '-I',
npm ERR! gyp info spawn args   '/Users/user1/Library/Caches/node-gyp/20.9.0/include/node/common.gypi',
npm ERR! gyp info spawn args   '-Dlibrary=shared_library',
npm ERR! gyp info spawn args   '-Dvisibility=default',
npm ERR! gyp info spawn args   '-Dnode_root_dir=/Users/user1/Library/Caches/node-gyp/20.9.0',
npm ERR! gyp info spawn args   '-Dnode_gyp_dir=/Users/user1/.nvm/versions/node/v20.9.0/lib/node_modules/npm/node_modules/node-gyp',
npm ERR! gyp info spawn args   '-Dnode_lib_file=/Users/user1/Library/Caches/node-gyp/20.9.0/<(target_arch)/node.lib',
npm ERR! gyp info spawn args   '-Dmodule_root_dir=/Users/user1/Projects/Raccord/webapp/node_modules/canvas',
npm ERR! gyp info spawn args   '-Dnode_engine=v8',
npm ERR! gyp info spawn args   '--depth=.',
npm ERR! gyp info spawn args   '--no-parallel',
npm ERR! gyp info spawn args   '--generator-output',
npm ERR! gyp info spawn args   'build',
npm ERR! gyp info spawn args   '-Goutput_dir=.'
npm ERR! gyp info spawn args ]
npm ERR! Package zlib was not found in the pkg-config search path.
npm ERR! Perhaps you should add the directory containing `zlib.pc'
npm ERR! to the PKG_CONFIG_PATH environment variable
npm ERR! Package 'zlib', required by 'cairo', not found
npm ERR! Package zlib was not found in the pkg-config search path.
npm ERR! Perhaps you should add the directory containing `zlib.pc'
npm ERR! to the PKG_CONFIG_PATH environment variable
npm ERR! Package 'zlib', required by 'libpng', not found
npm ERR! Package libffi was not found in the pkg-config search path.
npm ERR! Perhaps you should add the directory containing `libffi.pc'
npm ERR! to the PKG_CONFIG_PATH environment variable
npm ERR! Package 'libffi', required by 'gobject-2.0', not found
npm ERR! Package zlib was not found in the pkg-config search path.
npm ERR! Perhaps you should add the directory containing `zlib.pc'
npm ERR! to the PKG_CONFIG_PATH environment variable
npm ERR! Package 'zlib', required by 'freetype2', not found
npm ERR! gyp info ok 
npm ERR! gyp info it worked if it ends with ok
npm ERR! gyp info using node-gyp@9.4.0
npm ERR! gyp info using node@20.9.0 | darwin | arm64
npm ERR! gyp info spawn make
npm ERR! gyp info spawn args [ 'BUILDTYPE=Release', '-C', 'build' ]
npm ERR! In file included from ../src/backend/Backend.cc:1:
npm ERR! ../src/backend/Backend.h:3:10: fatal error: 'cairo.h' file not found
npm ERR! #include <cairo.h>
npm ERR!          ^~~~~~~~~
npm ERR! 1 error generated.
npm ERR! make: *** [Release/obj.target/canvas/src/backend/Backend.o] Error 1
npm ERR! gyp ERR! build error 
npm ERR! gyp ERR! stack Error: `make` failed with exit code: 2
npm ERR! gyp ERR! stack     at ChildProcess.onExit (/Users/user1/.nvm/versions/node/v20.9.0/lib/node_modules/npm/node_modules/node-gyp/lib/build.js:203:23)
npm ERR! gyp ERR! stack     at ChildProcess.emit (node:events:514:28)
npm ERR! gyp ERR! stack     at ChildProcess._handle.onexit (node:internal/child_process:294:12)
npm ERR! gyp ERR! System Darwin 23.1.0
npm ERR! gyp ERR! command "/Users/user1/.nvm/versions/node/v20.9.0/bin/node" "/Users/user1/.nvm/versions/node/v20.9.0/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js" "build" "--fallback-to-build" "--update-binary" "--module=/Users/user1/Projects/Raccord/webapp/node_modules/canvas/build/Release/canvas.node" "--module_name=canvas" "--module_path=/Users/user1/Projects/Raccord/webapp/node_modules/canvas/build/Release" "--napi_version=9" "--node_abi_napi=napi" "--napi_build_version=0" "--node_napi_label=node-v115"
npm ERR! gyp ERR! cwd /Users/user1/Projects/Raccord/webapp/node_modules/canvas
npm ERR! gyp ERR! node -v v20.9.0
npm ERR! gyp ERR! node-gyp -v v9.4.0
npm ERR! gyp ERR! not ok 
npm ERR! node-pre-gyp ERR! build error 
npm ERR! node-pre-gyp ERR! stack Error: Failed to execute '/Users/user1/.nvm/versions/node/v20.9.0/bin/node /Users/user1/.nvm/versions/node/v20.9.0/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js build --fallback-to-build --update-binary --module=/Users/user1/Projects/Raccord/webapp/node_modules/canvas/build/Release/canvas.node --module_name=canvas --module_path=/Users/user1/Projects/Raccord/webapp/node_modules/canvas/build/Release --napi_version=9 --node_abi_napi=napi --napi_build_version=0 --node_napi_label=node-v115' (1)
npm ERR! node-pre-gyp ERR! stack     at ChildProcess.<anonymous> (/Users/user1/Projects/Raccord/webapp/node_modules/@mapbox/node-pre-gyp/lib/util/compile.js:89:23)
npm ERR! node-pre-gyp ERR! stack     at ChildProcess.emit (node:events:514:28)
npm ERR! node-pre-gyp ERR! stack     at maybeClose (node:internal/child_process:1105:16)
npm ERR! node-pre-gyp ERR! stack     at ChildProcess._handle.onexit (node:internal/child_process:305:5)
npm ERR! node-pre-gyp ERR! System Darwin 23.1.0
npm ERR! node-pre-gyp ERR! command "/Users/user1/.nvm/versions/node/v20.9.0/bin/node" "/Users/user1/Projects/Raccord/webapp/node_modules/.bin/node-pre-gyp" "install" "--fallback-to-build" "--update-binary"
npm ERR! node-pre-gyp ERR! cwd /Users/user1/Projects/Raccord/webapp/node_modules/canvas
npm ERR! node-pre-gyp ERR! node -v v20.9.0
npm ERR! node-pre-gyp ERR! node-pre-gyp -v v1.0.11
npm ERR! node-pre-gyp ERR! not ok

npm ERR! A complete log of this run can be found in: /Users/user1/.npm/_logs/2023-11-27T13_44_56_912Z-debug-0.log

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