Monorepo下自定义TypeScript模块无法跨包导入导出类型求助

问题排查与修复步骤 #

• 第一步：确认monorepo workspace依赖关联正常
  大部分跨包导入失败的核心原因是未将导出类型的包作为工作区依赖引入导入方。首先在需要导入类型的包的package.json中添加对应依赖（以pnpm workspace为例，yarn/npm workspace规则类似）：

{
  "devDependencies": {
    "[你的导出包名]": "workspace:^" // 替换为实际的包名和对应的workspace版本规则
  }
}

配置完成后重新执行包管理器的install命令，确认node_modules中对应包是软链到本地的源码目录，而非从远程npm仓库下载的版本。

• 第二步：修正package.json的类型入口配置
  如果导出类型的包中配置了exports字段，TypeScript会优先读取exports中的类型声明，忽略外层的types字段，需要补充对应配置：

{
  "name": "[你的导出包名]",
  "types": "./types/index.d.ts",
  "exports": {
    ".": {
      "types": "./types/index.d.ts", // 必须显式声明类型入口，优先级高于外层的types
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  }
}

• 第三步：优化TypeScript配置适配monorepo场景
  1. 首先确认根目录tsconfig.json的compilerOptions.moduleResolution设置为bundler（TS 4.7及以上版本推荐）或node16，避免旧版模块解析逻辑的兼容问题
  2. 建议开启TypeScript项目引用实现更高效的本地类型同步，无需每次修改代码后手动构建类型：
     首先修改导出类型包的tsconfig：

     {
         "extends": "../../tsconfig.json",
         "compilerOptions": {
             "baseUrl": "./src",
             "rootDir": "./src",
             "outDir": "./dist",
             "declaration": true,
             "declarationDir": "./types",
             "composite": true, // 开启项目引用必填配置
             "declarationMap": true // 支持跳转到类型对应的源码位置
         },
         "include": [
             "./src"
         ],
         "exclude": [
             "node_modules",
             "dist"
         ]
     }
     

     然后在导入类型的包的tsconfig中添加引用声明：

     {
       "references": [
         { "path": "../[导出包所在的目录名称]" }
       ]
     }
     

• 第四步：确认导入写法与IDE缓存
  1. 导入类型时优先使用包名导入，避免使用跨包相对路径导入，示例：

  // 正确写法
  import type { SomeType } from '[你的导出包名]'
  // 不推荐的相对路径写法，容易触发类型解析异常
  import type { SomeType } from '../../[导出包目录]/src/index'
  

  2. 如果仅IDE提示类型错误，命令行执行tsc --noEmit无报错，重启IDE的TypeScript语言服务即可清除缓存问题。

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