JS+JSDoc的NPM Monorepo中TypeScript编译如何导入global.d.ts？

核心方案：打包单个声明文件 + 配置包类型入口 #

你遇到的问题本质是TS无法自动识别未生成声明文件的JS模块，而tsc默认生成的零散.d.ts文件过多。可以通过合并生成单个声明文件+配置包类型入口的方式解决，具体步骤如下：

1. 安装声明文件打包工具 #

在package C目录下安装dts-bundle-generator（专门用于将多份.d.ts合并为单个文件，支持CommonJS/ES模块）：

npm install -D dts-bundle-generator

2. 生成单个global.d.ts #

在package C的package.json中添加生成脚本，替换为你的实际入口文件路径：

"scripts": {
  "build:types": "dts-bundle-generator --out-file global.d.ts src/index.js"
}

运行npm run build:types，会在package C根目录生成包含所有导出类型的global.d.ts。

3. 配置package C的类型入口 #

修改package C的package.json，明确指定类型文件路径：

"name": "package-c", // 确保包名正确，A、B将用此名称导入
"main": "./src/index.js", // 保留原JS代码入口
"types": "./global.d.ts" // 关键：指定单个声明文件的路径

4. 配置A、B的类型解析 #

• 如果A、B通过包名导入（如import utils from 'package-c'）：
  确保Monorepo工作区配置正确（npm/yarn/pnpm workspaces均可），A、B的package.json依赖中包含"package-c": "*"或对应版本，TS会自动通过package C的types字段找到声明文件，无需额外修改A、B的jsconfig.json/tsconfig.json。
• 如果A、B通过相对路径导入（如import utils from '../package-c/src/index.js'）：
  在A、B的jsconfig.json/tsconfig.json的include数组中添加package C的声明文件路径：

  "include": [
    "src/**/*",
    "../package-c/global.d.ts"
  ]
  

常见问题排查 #

• 确认global.d.ts生成正确：打开文件检查是否包含package C所有导出的类型、函数、接口定义。
• 检查路径是否正确：package C的types字段路径需相对于包根目录，比如若global.d.ts在dist文件夹下，要写"./dist/global.d.ts"。
• 确保TS模块解析模式为node：A、B的jsconfig.json/tsconfig.json中compilerOptions.moduleResolution设为node（默认值，若被修改需恢复）。

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