React(TypeScript)集成OpenCV.js出现cv.Mat不是构造函数错误怎么解决

报错根因 #

你遇到的cv.Mat is not a constructor错误来自两个问题：

1. 你给script标签加了async属性，OpenCV.js脚本是异步加载的，组件初始化时脚本还没下载解析完成，window.cv此时为undefined
2. 你写的window.cv = window.cv || {}代码会把未加载完成的cv强制赋值为空对象，后续OpenCV.js加载完成后也不会覆盖已经存在的window.cv值，导致你拿到的cv一直是空对象，不存在Mat构造方法

修复步骤 #

1. 修改index.html中OpenCV.js的引入逻辑 #

移除async属性，新增加载完成的回调标记和自定义事件，方便React组件感知加载状态：

<script 
  src="https://docs.opencv.org/master/opencv.js" 
  type="text/javascript"
  onload="window.opencvLoaded = true; window.dispatchEvent(new Event('opencvReady'));"
></script>

2. 优化全局TS类型声明 #

不要在业务组件内写全局声明，在项目src目录下新建global.d.ts文件统一管理：

// src/global.d.ts
declare global {
  interface Window {
    cv: any; // 如需更完善的类型提示可安装@types/opencv.js后替换为对应的类型
    opencvLoaded?: boolean;
  }
}
export {};

同时删掉你之前在组件内写的window.cv = window.cv || {}这行代码。

3. 调整组件内调用逻辑 #

必须等OpenCV.js完全加载完成后再调用相关API，函数组件示例如下：

import { useEffect, useState } from 'react';

const OpenCVDemo = () => {
  // 标记OpenCV加载状态
  const [isCvReady, setIsCvReady] = useState(false);

  useEffect(() => {
    // 脚本已加载完成直接更新状态
    if (window.opencvLoaded) {
      setIsCvReady(true);
      return;
    }
    // 监听脚本加载完成事件
    const handleCvLoad = () => setIsCvReady(true);
    window.addEventListener('opencvReady', handleCvLoad);
    // 组件卸载时移除监听
    return () => window.removeEventListener('opencvReady', handleCvLoad);
  }, []);

  useEffect(() => {
    // 仅在加载完成后执行OpenCV相关逻辑
    if (!isCvReady) return;
    const dst = new cv.Mat();
    // 你的业务逻辑...
    // 用完必须调用delete释放内存避免泄漏
    dst.delete();
  }, [isCvReady]);

  return <div>{isCvReady ? 'OpenCV加载完成' : '加载中...'}</div>;
};

export default OpenCVDemo;

额外优化建议 #

如果不想用CDN引入，可直接安装npm包：

• 执行npm install @techstark/opencv-js @types/opencv.js安装官方封装的包和类型定义
• 直接在组件内import cv from '@techstark/opencv-js'即可使用，无需处理全局加载监听逻辑

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