如何让Docusaurus兼容仅ESM格式的TS库？

AI 小北

2026-7-6

解决Docusaurus与ESM格式TS库的兼容问题

核心排查与修复步骤

自定义Webpack解析规则
根目录package.json设置"type": "module"后，Docusaurus依赖的部分CJS文件可能被错误解析。在site/docusaurus.config.ts中添加Webpack配置，强制区分不同文件的解析方式：

export default defineConfig({
  // 其他配置项...
  webpack: {
    configure: (config) => {
      // 强制Docusaurus内部依赖按CJS解析
      config.module.rules.push({
        test: /node_modules\/(docusaurus|@docusaurus)\/.+\.js$/,
        resolve: { fullySpecified: false },
      });
      // 确保自身库源码按ESM解析
      config.module.rules.push({
        test: /src\/.+\.ts$/,
        type: 'javascript/auto',
        resolve: { extensionAlias: { '.ts': ['.ts', '.js'] } },
      });
      return config;
    },
  },
});

隔离TS配置作用域
修改根目录tsconfig.json，排除库源码目录，避免和Docusaurus的TS规则冲突：
```
{
  "extends": "@docusaurus/tsconfig",
  "compilerOptions": {
    "module": "ESNext",
    "target": "ES2020"
  },
  "exclude": ["src/**/*"]
}
```
同时保证tsconfig.lib.json的include仅指向src目录，专注于库的编译。
定位冲突文件
启用Webpack详细日志，运行Docusaurus时执行：
```
DEBUG=docusaurus:webpack yarn start
```
日志会输出所有被处理的文件路径，搜索CommonJS或require关键词即可定位被错误解析的文件。另外，可临时删除node_modules/.cache/docusaurus缓存目录，减少旧临时文件干扰。
调整库导入方式
文档中导入库代码时，直接引用编译后的ESM产物而非TS源码，例如：
```
import { myFunction } from '../dist/index.js';
```
避免Webpack直接处理未编译的源码，降低模块格式冲突概率。