升级Angular15与Typedoc后生成JSON缺失decorators字段的解决方法

问题背景 #

将应用升级至Angular 15，同时把Typedoc版本升级到0.23.28、TypeScript版本升级到4.8.4后，使用命令npx typedoc --entryPointStrategy expand ./src --json result.json生成的JSON文件中缺失decorators键值对。此前使用Angular 13、Typedoc 0.22.9、TypeScript 4.4.3时，生成的JSON正常包含该字段。

当前输出示例（缺失decorators）：

{
  "id": 7,
  "name": "myName",
  "kind": 1024,
  "kindString": "Property",
  "flags": {},
  "sources": [
    {
      "fileName": "app/app.component.ts",
      "line": 12,
      "character": 2
    }
  ],
  "type": {
    "type": "intrinsic",
    "name": "string"
  },
  "defaultValue": "'Gowthaman'"
}

期望输出示例（包含decorators）：

{
  "id": 6,
  "name": "myName",
  "kind": 1024,
  "kindString": "Property",
  "flags": {},
  "decorators": [
    {
      "name": "Input",
      "type": {
        "type": "reference",
        "qualifiedName": "InputDecorator",
        "package": "@angular/core",
        "name": "Input"
      },
      "arguments": {}
    }
  ],
  "sources": [
    {
      "fileName": "app.component.ts",
      "line": 12,
      "character": 2
    }
  ],
  "type": {
    "type": "intrinsic",
    "name": "string"
  },
  "defaultValue": "'Gowthaman'"
}

解决方案 #

方案1：显式启用装饰器相关配置 #

Typedoc 0.23.x版本调整了默认配置，需要显式开启装饰器元数据解析。可以通过两种方式实现：

命令行方式

直接在原有命令后添加参数：

npx typedoc --entryPointStrategy expand ./src --json result.json --experimentalDecorators --emitDecoratorMetadata --includeDeclarations

配置文件方式

在项目根目录创建typedoc.json，写入以下配置：

{
  "entryPointStrategy": "expand",
  "entryPoints": ["./src"],
  "json": "result.json",
  "experimentalDecorators": true,
  "emitDecoratorMetadata": true,
  "includeDeclarations": true
}

之后运行npx typedoc即可。

方案2：安装Angular专用Typedoc插件 #

如果方案1无效，可安装typedoc-plugin-angular插件，它专门针对Angular装饰器做了适配：

1. 安装插件

npm install typedoc-plugin-angular --save-dev

2. 运行Typedoc（插件会自动启用，无需额外配置）

npx typedoc --entryPointStrategy expand ./src --json result.json

原因说明 #

Typedoc 0.23版本对TypeScript装饰器的解析逻辑进行了优化，默认不再自动捕获装饰器元数据；同时新版本Angular的装饰器结构有变化，需要显式开启TypeScript编译的装饰器选项，或借助专用插件才能正确解析并输出decorators字段。

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