为什么我的TypeScript项目用typedoc生成文档后JSDoc注释没显示？

玲玲（打工版）提问于 2026-02-18 01:24:28 阅读 33

前端

我在Vue项目里用TypeDoc生成API文档，按文档写了JSDoc注释，但生成的HTML里参数说明就是不显示。试过检查注释格式，确认用了@param标签，还调整了typedoc.json的exclude配置，还是没反应。比如这个方法：


/**
 * 计算两个数值之和
 * @param {number} a - 第一个加数
 * @param {number} b - 第二个加数
 * @returns {number} 两数之和
 */
add(a: number, b: number) {
  return a + b
}

配置文件这样写的：


{
  "entryPoints": ["src"],
  "excludeExternals": true,
  "excludePrivate": true,
  "mode": "file"
}

生成的页面里方法列表倒是有了，就是参数和返回值描述全空白，控制台也没报错，这是哪里漏了吗？

我来解答赞 10 收藏

反馈

1 条解答

Des.芳芳 Lv1

问题出在TypeScript的类型声明和JSDoc混用上，TypeDoc默认会优先使用TS的类型信息，而忽略JSDoc里的类型声明。你的注释里写了类似 @param {number} a 这种带类型的声明，但TypeScript已经通过 a: number 知道了类型，导致TypeDoc直接跳过了JSDoc解析。

直接改配置文件，加上 jsDocCompatibility 选项：

{

  "entryPoints": ["src"],

  "excludeExternals": true,

  "excludePrivate": true,

  "mode": "file",

  "jsDocCompatibility": {

    "exampleTag": true,

    "ignoreDiagnositcs": true

  }

}

另外，把注释简化一下，不需要写类型声明，TypeDoc自己会读取TS的类型：

/**

 * 计算两个数值之和

 * @param a 第一个加数

 * @param b 第二个加数

 * @returns 两数之和

 */

add(a: number, b: number) {

  return a + b

}

记得升级到最新版TypeDoc，老版本对Vue项目支持不太好。如果还是不行，检查下tsconfig.json里是不是开启了 stripInternal 或者 removeComments，这两个选项会导致注释被干掉。

最后提醒一句，Vue项目用TypeDoc时最好把 .vue 文件单独处理下，不然容易踩坑。我之前搞了个脚本专门提取这些文件的注释，有需要可以参考下。

2026-02-18 03:00