为何静态导入pdfjs-lib会返回Promise？Webpack+TS场景

问题成因 #

你把pdfjs-lib的Webpack别名直接指向了mozilla/pdf.js的src/pdf.js文件，但这个源码入口的默认导出是一个Promise，而非常规的同步API对象。当你用import * as lib导入时，拿到的模块对象里包含了这个异步导出的Promise，所以打印结果会显示[object Promise]。这是pdf.js源码本身的设计逻辑——它的源码入口需要异步初始化环境、加载依赖，因此返回Promise，和Webpack或TypeScript的配置本身无关。

解决方案 #

1. 改用官方预构建包（推荐） #

放弃直接引用源码，安装官方打包好的pdfjs-dist包：

npm install pdfjs-dist

之后直接正常导入即可：

import * as pdfjsLib from 'pdfjs-dist';
// 直接调用API，比如：
const doc = await pdfjsLib.getDocument('test.pdf').promise;

2. 若必须使用源码文件 #

如果一定要用src/pdf.js，需要等待Promise resolve后再使用API：

import * as pdfModule from 'pdfjs-lib';

// 等待模块导出的Promise完成
const pdfjsLib = await pdfModule.default;
// 之后正常调用API
const page = await pdfjsLib.getDocument('test.pdf').promise.then(doc => doc.getPage(1));

配置调整建议 #

Webpack别名修正 #

你的Webpack别名配置大概率是类似这样：

module.exports = {
  resolve: {
    alias: {
      'pdfjs-lib': path.resolve(__dirname, 'node_modules/mozilla/pdf.js/src/pdf.js')
    }
  }
};

把别名指向预构建的文件，就能避免异步导出问题：

'pdfjs-lib': path.resolve(__dirname, 'node_modules/pdfjs-dist/build/pdf.js')

tsconfig.json优化 #

确保TypeScript的模块配置和Webpack兼容，比如：

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "NodeNext",
    "target": "ES2020",
    "allowSyntheticDefaultImports": true
  }
}

开启allowSyntheticDefaultImports可以更顺畅处理模块互导场景。

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