在TypeScript中导入Shaka Player遇TS2306错误的技术问询

问题说明 #

在TypeScript模块中导入Shaka Player UI时使用以下代码：

import shaka from 'shaka-player/dist/shaka-player.ui';

编译器抛出错误：

TS2306: File '~/dist/shaka-player.ui.d.ts' is not a module.

已确认dist目录下存在对应的类型声明文件和JS构建文件，当前tsconfig编译选项如下：

"compilerOptions": {
  "target": "esnext",
  "module": "esnext",
  "strict": true,
  "jsx": "preserve",
  "importHelpers": true,
  "moduleResolution": "node",
  "skipLibCheck": true,
  "esModuleInterop": true,
  "allowSyntheticDefaultImports": true,
  "sourceMap": true,
  "baseUrl": ".",
  "allowJs": true,
  "checkJs": false,
  "types": [
    "webpack-env",
    "jest"
  ],
  "paths": {
    "@/*": [
      "src/*"
    ]
  },
  "lib": [
    "esnext",
    "dom",
    "dom.iterable",
    "scripthost"
  ]
}

可行解决方法 #

1. 调整导入方式 #

Shaka Player UI的类型声明可能未正确导出默认模块，试试以下两种导入方式：

// 命名导入整个模块
import * as shaka from 'shaka-player/dist/shaka-player.ui';

// 先导入核心库，再加载UI扩展（更推荐）
import shaka from 'shaka-player';
import 'shaka-player/dist/shaka-player.ui';

第二种方式中，UI模块会自动挂载到核心shaka对象上，无需单独导出。

2. 修正类型声明文件 #

打开shaka-player.ui.d.ts，检查文件顶部是否有正确的模块声明。如果没有，手动添加：

declare module 'shaka-player/dist/shaka-player.ui' {
  import shaka from 'shaka-player';
  export = shaka;
}

由于UI仅作为核心模块的扩展，这样声明可让TypeScript识别其归属关系。

3. 修改tsconfig配置 #

如果使用webpack 5+或Vite等现代构建工具，可将moduleResolution改为bundler；另外，把shaka-player加入types数组，确保全局类型被加载：

"types": [
  "webpack-env",
  "jest",
  "shaka-player"
]

4. 更新包版本 #

旧版本的shaka-player可能存在类型声明bug，尝试更新到最新版：

npm update shaka-player
# 或使用yarn
yarn upgrade shaka-player

内容的提问来源于stack exchange，提问作者Trabelsi Mohamed Hedi