TypeDoc
TypeScript 生态的 API 文档自动生成工具
文档工具组件开发TypeScriptAPI 文档
从 TS 源码、类型注解和 TSDoc 注释生成静态 HTML 文档站，为组件库、工具库和 SDK 提供类型级 API 参考。
TypeDoc TypeScript API 文档生成器技术调研
TypeDoc 是 TypeScript 生态的 API 文档自动生成工具，从 TS 源码、类型注解和 TSDoc 注释生成静态 HTML 文档站。在组件开发与调试 workflow 中，它为 packages/ui、工具库和 SDK 提供类型级 API 参考，与 Storybook（可视化）和 VitePress（用法指南）形成互补。
一、 基本信息
| 维度 | 关键指标 / 描述 |
|---|---|
| 技术标签 | API 文档 / TypeScript / TSDoc / 静态生成 |
| 开发商 | TypeDoc 开源社区 |
| 官方网站 | https://typedoc.org/ |
| GitHub 仓库 | TypeStrong/typedoc |
| npm 包 | typedoc |
| 许可协议 | Apache 2.0 |
| 首次发布 | 2013 年 |
| 当前版本 | TypeDoc 0.27.x+ |
| 生态成熟度 | 高（TS 库 API 文档标准） |
二、 技术定位与简介
TypeDoc 从 TypeScript 编译器 API 提取：
- 模块、类、接口、类型别名、枚举。
- 函数签名、泛型参数、返回值。
- TSDoc/JSDoc 注释描述与
@param、@example。 - 继承关系、实现接口图谱。
输出静态 HTML（或 JSON），可部署为独立 API 文档子站，或嵌入 Docusaurus/VitePress 链接。
三、 快速上手安装说明
1. 安装
pnpm add -D typedoc2. typedoc.json
{
"entryPoints": ["src/index.ts"],
"out": "docs-api",
"plugin": ["typedoc-plugin-markdown"],
"readme": "README.md"
}3. package.json
{
"scripts": {
"docs:api": "typedoc"
}
}4. TSDoc 注释示例
/**
* 格式化用户显示名称
* @param user - 用户对象
* @returns 用于 UI 展示的字符串
* @example
* ```ts
* formatDisplayName({ firstName: 'A', lastName: 'B' })
* // => 'A B'
* ```
*/
export function formatDisplayName(user: User): string {
return `${user.firstName} ${user.lastName}`.trim()
}5. 运行
pnpm docs:api四、 核心特性
1. 类型精确
直接读 TS 类型系统，签名准确。
2. 反射结构
模块树、继承图、类型层次导航。
3. 插件系统
markdown 导出、external module map、merge 等。
4. 主题定制
默认主题可换肤或输出 JSON 供自定义 UI。
5. monorepo 支持
entryPointStrategy: 'packages' 多包文档。
6. 版本化
CI 按 tag 发布不同版本 API 文档。
7. 与 TS 版本同步
需匹配项目 TypeScript 版本。
五、 适用场景
1. 黄金适用场景
packages/ui组件 props 类型 API 参考。- 内部 SDK、工具函数库文档。
- 开源 npm 包 API 站点。
- 调试时查阅类型定义与注释。
- CI 自动生成 API 文档 artifact。
2. 局限适用场景
- 非 TypeScript 项目。
- 视觉组件展示（Storybook）。
- 叙事性教程（VitePress）。
- 运行时行为文档（需手写指南）。
六、 技术亮点
1. 类型即文档
减少签名与文档脱节。
2. TS 官方工具链一环
与 tsc、TSDoc 标准对齐。
3. 零运行时
纯静态生成，安全部署。
4. 插件扩展
可输出 Markdown 纳入 VitePress。
七、 核心概念与架构
digraph TypeDoc_Arch {
rankdir=LR
node [shape=box, style="rounded,filled", fillcolor="#f0f9ff"]
TS [label="TypeScript Sources", fillcolor="#bae6fd"]
TSC [label="TS Compiler API"]
TD [label="TypeDoc"]
HTML [label="HTML / JSON Docs"]
TS -> TSC
TSC -> TD
TD -> HTML
}八、 技术局限与边界
- 仅静态结构：不展示组件渲染效果。
- 注释质量依赖作者：无注释则文档贫瘠。
- 复杂泛型可读性：部分类型展示难读。
- 构建需完整 TS 项目：配置不当易报错。
- UI 默认主题一般：深度定制需 effort。
- Vue SFC：需额外配置或 vite-plugin-dts 等补充。
九、 生态地图
| 类别 | 工具 |
|---|---|
| 替代 | API Extractor、documentation.js |
| Vue | vue-docgen-api、vite-plugin-dts |
| 嵌入 | Docusaurus TypeDoc 插件 |
| 导出 | typedoc-plugin-markdown |
十、 生态集成
| 方向 | 说明 |
|---|---|
| VitePress | Markdown 插件输出纳入 docs。 |
| Storybook | autodocs 补视觉，TypeDoc 补类型细节。 |
| CI | tag 发布时 typedoc 部署 GitHub Pages。 |
| 本项目 | packages/ui API 参考生成。 |
十一、 开发与工程化
1. 公共 API 入口
src/index.ts 显式 export，控制文档范围。
2. @internal 隐藏
TSDoc @internal 或 excludeInternal 排除实现细节。
3. monorepo
{
"entryPointStrategy": "packages",
"entryPoints": ["packages/ui", "packages/prompts"]
}十二、 性能与安全
- 生成速度快，适合 CI。
- 勿在注释中写 secrets。
- 内部 API 文档部署加访问控制。
十三、 技术对比
| 工具 | 优势 | 适合 |
|---|---|---|
| TypeDoc | TS 原生、准确 | TS 库 API |
| Storybook Autodocs | 组件视觉 | UI 组件 |
| JSDoc | JS 无类型 | 纯 JS 项目 |
| vite-plugin-dts | 发 .d.ts | 打包类型声明 |
十四、 最佳实践
- 公共导出写完整 TSDoc，含
@example。 excludePrivate/@internal隐藏实现。- CI 与版本 tag 联动发布 API 文档。
- 与 Storybook 互链：用法看 Story，类型看 TypeDoc。
- 破坏性变更在 CHANGELOG 与 TypeDoc 同步说明。
- monorepo 统一 typedoc.json 基配置 extends。