Node.js 18.20.3下Electron集成canvas启动失败问题求助

我有一个基于Electron Forge运行的Electron应用，当前使用版本：

• Node.js 18.20.3
• Electron 33.0.1
• Electron Forge 7.5.0

执行npm run start启动项目时，只要依赖canvas模块就启动失败；删除canvas相关代码并卸载模块后，应用能正常重建。启动失败的报错信息如下：

Done Building Project "C:\Users\rikim\Documents\appangular\oneapp-ui\node_modules\canvas\build\binding.sln" (default targets) -- FAILED.

Build FAILED.

"C:\Users\rikim\Documents\appangular\oneapp-ui\node_modules\canvas\build\binding.sln" (default target) (1) ->
"C:\Users\rikim\Documents\appangular\oneapp-ui\node_modules\canvas\build\canvas-postbuild.vcxproj.metaproj" (default target) (2) ->
"C:\Users\rikim\Documents\appangular\oneapp-ui\node_modules\canvas\build\canvas.vcxproj" (default target) (3) ->
(ClCompile target) ->
  C:\Users\rikim\.electron-gyp\33.0.2\include\node\v8-primitive.h(616,62): warning C4324: 'v8::String::ValueView': structure was padded due to alignment specifier [C:\Users\rikim\Documents\appangular\oneapp-ui\node_modules\canvas\build\canvas.vcxproj]


"C:\Users\rikim\Documents\appangular\oneapp-ui\node_modules\canvas\build\binding.sln" (default target) (1) ->
"C:\Users\rikim\Documents\appangular\oneapp-ui\node_modules\canvas\build\canvas-postbuild.vcxproj.metaproj" (default target) (2) ->
"C:\Users\rikim\Documents\appangular\oneapp-ui\node_modules\canvas\build\canvas.vcxproj" (default target) (3) ->
(ClCompile target) ->
  C:\Users\rikim\Documents\appangular\oneapp-ui\node_modules\nan\nan_scriptorigin.h(36,23): error C2665: 'v8::ScriptOrigin::ScriptOrigin': no overloaded function could convert all the argument types [C:\Users\rikim\Documents\appangular\oneapp-ui\node_modules\canvas\build\canvas.vcxproj]
  C:\Users\rikim\Documents\appangular\oneapp-ui\node_modules\nan\nan_scriptorigin.h(40,23): error C2665: 'v8::ScriptOrigin::ScriptOrigin': no overloaded function could convert all the argument types [C:\Users\rikim\Documents\appangular\oneapp-ui\node_modules\canvas\build\canvas.vcxproj]
  C:\Users\rikim\Documents\appangular\oneapp-ui\node_modules\nan\nan_scriptorigin.h(47,23): error C2665: 'v8::ScriptOrigin::ScriptOrigin': no overloaded function could convert all the argument types [C:\Users\rikim\Documents\appangular\oneapp-ui\node_modules\canvas\build\canvas.vcxproj]

    1 Warning(s)
    3 Error(s)

Time Elapsed 00:00:02.61
Error: `C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\MSBuild\Current\Bin\MSBuild.exe` failed with exit code: 1
    at ChildProcess.<anonymous> (C:\Users\rikim\Documents\appangular\oneapp-ui\node_modules\@electron\node-gyp\lib\build.js:215:23)
    at ChildProcess.emit (node:events:517:28)
    at ChildProcess._handle.onexit (node:internal/child_process:292:12)

× Rebuild Failed

An unhandled error occurred inside electron-rebuild
node-gyp failed to rebuild 'C:\Users\rikim\Documents\appangular\oneapp-ui\node_modules\canvas'

Error: node-gyp failed to rebuild 'C:\Users\rikim\Documents\appangular\oneapp-ui\node_modules\canvas'
    at ChildProcess.<anonymous> (C:\Users\rikim\Documents\appangular\oneapp-ui\node_modules\@electron\rebuild\lib\module-type\node-gyp\node-gyp.js:121:24)
    at ChildProcess.emit (node:events:517:28)
    at ChildProcess._handle.onexit (node:internal/child_process:292:12)

解决方案 #

1. 升级canvas到兼容版本 #

Electron 33基于Node.js 20的V8引擎，旧版canvas依赖的nan库不兼容新V8 API。执行以下命令升级canvas：

npm uninstall canvas
npm install canvas@latest

若最新版仍有问题，可尝试指定canvas@2.11.2及以上版本（这类版本已适配新V8 API）。

2. 强制重建canvas模块 #

升级后若报错依旧，手动触发electron-rebuild重新构建canvas的native模块：

npx electron-rebuild -f -w canvas

也可以在项目的package.json的scripts字段中添加：

"rebuild:canvas": "electron-rebuild -f -w canvas"

之后执行npm run rebuild:canvas完成构建。

3. 更新nan依赖库 #

canvas依赖的nan版本过低会导致V8 API不兼容，手动更新nan：

npm install nan@latest --save-dev

4. 确认Windows构建环境 #

确保已安装Visual Studio 2022 Build Tools（需包含C++开发组件），并验证msvs_version配置：

npm config get msvs_version

若输出不是2022，执行以下命令全局配置：

npm config set msvs_version 2022 --global

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