如何在NestJS中使用Konva？Node.js环境运行Konva报错解决

报错根因 #

• Konva 主入口默认适配浏览器环境，直接导入会尝试读取window、document等Node环境不存在的DOM API，直接触发启动报错
• 未安装Konva在Node环境运行的必须依赖canvas
• NestJS默认构建逻辑会打包服务端依赖，容易破坏canvas这类包含二进制产物的原生包

正确集成步骤 #

• 安装核心依赖

npm install konva canvas
# yarn 用户执行 yarn add konva canvas
# pnpm 用户执行 pnpm add konva canvas

• 修正导入路径，所有使用Konva的文件都要指定Node端入口，禁止直接导入konva默认包

// 错误写法 会触发浏览器API缺失报错
// import Konva from 'konva'

// 正确写法
import Konva from 'konva/lib/index-node';

如果TypeScript提示模块类型找不到，在项目全局类型声明文件（一般是src/typings.d.ts，没有就新建）中添加以下声明：

declare module 'konva/lib/index-node';

• 修改NestJS构建配置，避免打包时破坏原生依赖，打开项目根目录的nest-cli.json，添加外部依赖配置：

{
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "externalDependencies": ["canvas", "konva"]
  }
}

功能验证 #

可以编写测试服务验证集成是否正常：

import { Injectable } from '@nestjs/common';
import Konva from 'konva/lib/index-node';

@Injectable()
export class KonvaTestService {
  generateTestImage() {
    // Node环境初始化Stage不需要传container参数，仅需指定宽高
    const stage = new Konva.Stage({
      width: 600,
      height: 400
    });
    const layer = new Konva.Layer();
    stage.add(layer);

    // 添加测试图形
    const testRect = new Konva.Rect({
      x: 50,
      y: 50,
      width: 200,
      height: 100,
      fill: '#1677ff',
      cornerRadius: 8
    });
    layer.add(testRect);

    // 导出图片base64
    return stage.toDataURL();
  }
}

调用上述方法如果能正常返回base64格式的图片数据，说明集成成功。

常见问题排查 #

• 若canvas依赖安装失败，先确认本地具备Node原生模块编译环境：Windows需安装windows-build-tools，Mac需安装Xcode命令行工具，Linux需预先安装build-essential、libcairo2-dev、libjpeg-dev、libpango1.0-dev等系统依赖
• 若项目使用自定义Webpack配置构建NestJS服务，需要将canvas、konva加入webpack的externals列表，避免打包二进制文件导致运行错误
• ESM模块模式的项目如果导入报错，可以改用CommonJS方式导入：const Konva = require('konva/lib/index-node')

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