NX集成Monorepo中TSOA执行spec命令报错：未找到类型声明

我有一个NX集成的Monorepo，包含两个包：

apps/mtb-api
  包含Express API
  使用TSOA构建Swagger文档
  包含tsconfig.json
libs/mtb-requests
  包含供API使用的接口定义
  包含tsconfig.json
tsconfig.base.json

执行命令：

cd apps/api && npx tsoa spec

时出现以下错误：

GenerateMetadataError: No declarations found for referenced type ISwitchTenantResponse.
at TypeResolver.getModelTypeDeclaration (C:\Source\mtb-v3\node_modules@tsoa\cli\dist\metadataGeneration\typeResolver.js:758:19)
at TypeResolver.typeArgumentsToContext (C:\Source\mtb-v3\node_modules@tsoa\cli\dist\metadataGeneration\typeResolver.js:886:34)
at TypeResolver.getReferenceType (C:\Source\mtb-v3\node_modules@tsoa\cli\dist\metadataGeneration\typeResolver.js:579:14)
at TypeResolver.resolve (C:\Source\mtb-v3\node_modules@tsoa\cli\dist\metadataGeneration\typeResolver.js:390:36)
at C:\Source\mtb-v3\node_modules@tsoa\cli\dist\metadataGeneration\typeResolver.js:132:118
at Array.reduce (<anonymous>)
at TypeResolver.resolve (C:\Source\mtb-v3\node_modules@tsoa\cli\dist\metadataGeneration\typeResolver.js:131:18)
at TypeResolver.resolve (C:\Source\mtb-v3\node_modules@tsoa\cli\dist\metadataGeneration\typeResolver.js:380:118)
at MethodGenerator.Generate (C:\Source\mtb-v3\node_modules@tsoa\cli\dist\metadataGeneration\methodGenerator.js:39:78)
at C:\Source\mtb-v3\node_modules@tsoa\cli\dist\metadataGeneration\controllerGenerator.js:46:41

相关配置文件 #

根目录tsconfig.base.json #

{
  "compileOnSave": false,
  "compilerOptions": {
    "rootDir": ".",
    "sourceMap": true,
    "declaration": false,
    "moduleResolution": "node",
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "noImplicitAny": true,
    "importHelpers": true,
    "target": "es2015",
    "module": "esnext",
    "lib": ["es2020", "dom"],
    "skipLibCheck": true,
    "skipDefaultLibCheck": true,
    "baseUrl": ".",
    "resolveJsonModule": true,
    "paths": {
      "@mtb/mtb-requests": ["libs/mtb-requests/src/index.ts"]
    }
  },
  "exclude": ["node_modules", "tmp"]
}

API的tsconfig.json #

{
  "extends": "../../tsconfig.base.json",
  "files": [],
  "include": [],
  "references": [
    {
      "path": "./tsconfig.app.json"
    },
    {
      "path": "./tsconfig.spec.json"
    }
  ],
  "compilerOptions": {
    "esModuleInterop": true,
  }
}

mtb-requests库的tsconfig.json #

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "module": "commonjs"
  },
  "files": [],
  "include": [],
  "references": [
    {
      "path": "./tsconfig.lib.json"
    },
    {
      "path": "./tsconfig.spec.json"
    }
  ]
}

mtb-api应用中的tsoa.json #

{
  "entryFile": "src/index.ts",
  "noImplicitAdditionalProperties": "throw-on-extras",
  "spec": {
    "outputDirectory": "public",
    "specVersion": 3
  }
}

这个错误源于TSOA无法读取Monorepo中mtb-requests包的类型定义，核心原因是类型声明未生成，且TSOA未正确识别项目引用路径。

1. 开启类型声明生成
   修改根目录tsconfig.base.json中的declaration选项为true，让TypeScript为mtb-requests生成.d.ts类型文件：

"declaration": true,

2. 指定TSOA使用的tsconfig
   在mtb-api的tsoa.json中添加tsconfig字段，指向API的实际业务配置文件（比如tsconfig.app.json），确保TSOA能识别项目引用和路径映射：

{
  "entryFile": "src/index.ts",
  "noImplicitAdditionalProperties": "throw-on-extras",
  "spec": {
    "outputDirectory": "public",
    "specVersion": 3
  },
  "tsconfig": "./tsconfig.app.json"
}

3. 先编译依赖包
   执行TSOA命令前，先编译mtb-requests包以生成类型声明：

npx nx build mtb-requests

4. 使用NX命令执行TSOA
   推荐用NX的run命令来执行TSOA，避免路径问题：

npx nx run mtb-api:tsoa-spec

（需在mtb-api的project.json中配置对应的target，示例：

"targets": {
  "tsoa-spec": {
    "executor": "nx:run-commands",
    "options": {
      "command": "npx tsoa spec"
    }
  }
}

）

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