为何仅在生成Typedoc文档时出现TS2322类型错误？

API 探路者

2026-7-1

Typedoc类型解析与项目编译工具不一致的排查方案

问题场景

项目中存在如下TypeScript代码：

public doSomething(val: number | undefined | null | string): string | undefined | null {
  if (val === null || val === undefined || typeof val === 'string') {
    return val;
  }
  ...
}

WebStorm无语法报错，悬停返回语句中的val显示类型为string | null | undefined；通过nx serve运行应用编译正常，但使用Typedoc生成HTML文档时，返回语句触发TS2322错误：

TS2322: Type 'string | number' is not assignable to type 'string'.
Type 'number' is not assignable to type 'string'.

排查与配置要点

检查Typedoc依赖的TypeScript版本
项目编译使用的TS版本可能和Typedoc内置的TS版本不匹配，导致类型解析逻辑差异。执行npm ls typescript查看项目根目录及Typedoc依赖的TS版本，确保两者一致，或统一升级到相同稳定版本。
确保Typedoc正确读取项目TS配置
确认typedoc.config.json是否显式指定了项目的tsconfig.json路径。若未指定，Typedoc可能使用默认配置而非项目的编译规则，可在配置文件中添加：
```
{
  "tsconfig": "./tsconfig.json"
  // 其他原有配置
}
```
对比模块间的TS配置差异
由于函数复制到其他模块无报错，说明当前模块的tsconfig存在特殊配置。对比报错模块与正常模块的tsconfig.json，重点关注strict、strictNullChecks、strictFunctionTypes等严格模式选项，Typedoc对这类选项的处理可能与项目编译工具存在差异。
排查Typedoc插件或自定义配置干扰
若项目使用了Typedoc插件，或typedoc.config.json中有自定义类型处理规则，可能导致解析异常。可临时禁用所有插件，使用最简配置生成文档，验证是否为插件导致的问题。
临时规避方案（非根治）
若以上排查无效，可在返回语句中显式断言类型绕过检查：
```
return val as string | null | undefined;
```