React+TypeScript中Wavesurfer.js Cursor插件导入报错及优化方案问询

问题分析 #

你遇到的矛盾源于：@types/wavesurfer.js 基于wavesurfer.js源码目录（src/）编写类型声明，但npm发布的包中，src/目录未被Webpack等构建工具默认识别，导致导入src/路径插件时编译报错；而导入dist/路径的编译后文件能运行，却无法关联类型声明。

最优解决方案 #

方案1：使用官方推荐的插件导入路径（优先选择） #

若你的wavesurfer.js版本为v7及以上，直接从官方打包的插件路径导入：

import CursorPlugin from 'wavesurfer.js/plugins/cursor';

此路径既被构建工具正确解析，又能自动关联@types/wavesurfer.js的完整类型提示，无需额外配置。

方案2：配置构建工具识别源码路径 #

若需使用源码路径导入，可通过TypeScript和Webpack配置解决模块解析问题：

1. 修改tsconfig.json添加路径别名：

{
  "compilerOptions": {
    "paths": {
      "wavesurfer.js/src/*": ["./node_modules/wavesurfer.js/src/*"]
    }
  }
}

2. 修改Webpack配置添加别名：

const path = require('path');

module.exports = {
  // ...其他配置
  resolve: {
    alias: {
      'wavesurfer.js/src': path.resolve(__dirname, 'node_modules/wavesurfer.js/src')
    }
  }
};

配置完成后，即可继续使用import CursorPlugin from 'wavesurfer.js/src/plugin/cursor.js';，同时保留类型提示且编译正常。

方案3：手动补充类型声明（兜底方案） #

若必须使用dist/路径的文件，可通过自定义类型声明文件复用源码类型：
在项目中创建wavesurfer-cursor.d.ts文件，内容如下：

import type { Plugin } from 'wavesurfer.js';

declare module 'wavesurfer.js/dist/plugin/wavesurfer.cursor.min.js' {
  const CursorPlugin: typeof import('wavesurfer.js/src/plugin/cursor.js').default;
  export default CursorPlugin;
}

之后导入dist/路径的插件时，TypeScript会自动关联源码的类型声明，获得完整提示。

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