TypeDoc 安装与配置 #

环境要求 #

在安装 TypeDoc 之前，请确保你的开发环境满足以下要求：

必需环境 #

text

┌─────────────────────────────────────────────────────────────┐
│                    环境要求                                  │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Node.js >= 16.0.0                                         │
│  ├── 推荐 LTS 版本                                         │
│  └── 使用 nvm 管理版本                                     │
│                                                             │
│  TypeScript >= 4.7                                          │
│  ├── 作为 peerDependency                                   │
│  └── 建议与项目版本一致                                     │
│                                                             │
│  包管理器                                                    │
│  ├── npm >= 7.0.0                                          │
│  ├── yarn >= 1.22                                          │
│  └── pnpm >= 7.0.0                                         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

检查环境 #

bash

# 检查 Node.js 版本
node --version
# v18.17.0 或更高

# 检查 npm 版本
npm --version
# 9.6.0 或更高

# 检查 TypeScript 版本
npx tsc --version
# Version 5.0.0 或更高

安装 TypeDoc #

使用 npm 安装 #

bash

# 安装为开发依赖
npm install --save-dev typedoc

# 同时确保安装了 TypeScript
npm install --save-dev typescript

使用 yarn 安装 #

bash

# 安装为开发依赖
yarn add --dev typedoc typescript

使用 pnpm 安装 #

bash

# 安装为开发依赖
pnpm add --save-dev typedoc typescript

验证安装 #

bash

# 检查 TypeDoc 版本
npx typedoc --version
# TypeDoc 0.25.x

# 查看帮助信息
npx typedoc --help

快速开始 #

最简单的使用方式 #

创建一个简单的 TypeScript 文件：

typescript

// src/index.ts

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

/**
 * 用户信息接口
 */
export interface User {
  /** 用户ID */
  id: number;
  /** 用户名 */
  name: string;
  /** 邮箱地址 */
  email: string;
}

/**
 * 用户服务类
 */
export class UserService {
  private users: User[] = [];

  /**
   * 添加用户
   * @param user - 用户信息
   */
  addUser(user: User): void {
    this.users.push(user);
  }

  /**
   * 获取所有用户
   * @returns 用户列表
   */
  getUsers(): User[] {
    return this.users;
  }
}

生成文档 #

bash

# 最简单的方式：指定入口文件和输出目录
npx typedoc src/index.ts --out docs

# 输出：
# Documentation generated at ./docs

查看生成的文档 #

bash

# 在浏览器中打开
open docs/index.html  # macOS
start docs/index.html # Windows
xdg-open docs/index.html # Linux

配置方式 #

TypeDoc 支持多种配置方式，你可以根据项目需求选择最适合的方式。

1. 命令行参数 #

直接在命令行中指定配置：

bash

npx typedoc \
  --entryPoints src/index.ts \
  --out docs \
  --plugin typedoc-plugin-markdown \
  --readme README.md \
  --name "My Project" \
  --includeVersion

2. typedoc.json 配置文件 #

创建 typedoc.json 文件：

json

{
  "entryPoints": ["src/index.ts"],
  "out": "docs",
  "name": "My Project",
  "includeVersion": true,
  "readme": "./README.md"
}

运行：

bash

npx typedoc
# 自动读取 typedoc.json

3. package.json 配置 #

在 package.json 中添加 typedocOptions 字段：

json

{
  "name": "my-project",
  "version": "1.0.0",
  "typedocOptions": {
    "entryPoints": ["src/index.ts"],
    "out": "docs",
    "name": "My Project",
    "includeVersion": true
  }
}

4. TypeScript 配置文件 #

在 tsconfig.json 中添加 typedocOptions：

json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "strict": true,
    "outDir": "./dist"
  },
  "typedocOptions": {
    "entryPoints": ["src/index.ts"],
    "out": "docs"
  }
}

配置优先级 #

text

┌─────────────────────────────────────────────────────────────┐
│                    配置优先级（从高到低）                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. 命令行参数                                              │
│     npx typedoc --out custom-docs                          │
│                                                             │
│  2. typedoc.json 文件                                       │
│     项目根目录下的配置文件                                   │
│                                                             │
│  3. package.json 中的 typedocOptions                       │
│     package.json 内的配置                                   │
│                                                             │
│  4. tsconfig.json 中的 typedocOptions                      │
│     TypeScript 配置文件内的配置                             │
│                                                             │
└─────────────────────────────────────────────────────────────┘

常用配置选项 #

基本配置 #

json

{
  "entryPoints": ["src/index.ts"],
  "out": "docs",
  "name": "My Project API",
  "includeVersion": true,
  "readme": "./README.md"
}

入口点配置 #

json

{
  "entryPoints": [
    "src/index.ts",
    "src/utils/index.ts",
    "src/services/index.ts"
  ],
  "entryPointStrategy": "resolve"
}

输出配置 #

json

{
  "out": "docs",
  "json": "docs/api.json",
  "pretty": true,
  "emit": "docs"
}

包含/排除配置 #

json

{
  "entryPoints": ["src"],
  "exclude": [
    "node_modules",
    "**/*.test.ts",
    "**/*.spec.ts",
    "src/internal/**"
  ],
  "excludePrivate": true,
  "excludeProtected": false,
  "excludeInternal": true,
  "externalPattern": ["**/node_modules/**"]
}

类型解析配置 #

json

{
  "tsconfig": "./tsconfig.json",
  "compilerOptions": {
    "skipLibCheck": true
  }
}

完整配置示例 #

小型项目配置 #

json

{
  "entryPoints": ["src/index.ts"],
  "out": "docs",
  "name": "My Library",
  "includeVersion": true,
  "readme": "./README.md",
  "excludePrivate": true,
  "excludeInternal": true
}

中型项目配置 #

json

{
  "entryPoints": [
    "src/core/index.ts",
    "src/utils/index.ts",
    "src/plugins/index.ts"
  ],
  "out": "docs",
  "name": "My Project",
  "includeVersion": true,
  "readme": "./README.md",
  "exclude": [
    "**/*.test.ts",
    "**/*.spec.ts",
    "src/internal/**"
  ],
  "excludePrivate": true,
  "excludeProtected": false,
  "excludeInternal": true,
  "theme": "default",
  "gaID": "UA-XXXXX-Y",
  "hideGenerator": true
}

大型项目配置 #

json

{
  "entryPoints": [
    {
      "entryPoint": "src/packages/core/index.ts",
      "displayName": "Core"
    },
    {
      "entryPoint": "src/packages/utils/index.ts",
      "displayName": "Utils"
    },
    {
      "entryPoint": "src/packages/cli/index.ts",
      "displayName": "CLI"
    }
  ],
  "entryPointStrategy": "packages",
  "out": "docs",
  "name": "Monorepo Project",
  "includeVersion": true,
  "exclude": [
    "**/node_modules/**",
    "**/*.test.ts",
    "**/*.spec.ts",
    "**/dist/**"
  ],
  "excludePrivate": true,
  "excludeInternal": true,
  "sort": ["source-order"],
  "visibilityFilters": {
    "protected": true,
    "private": false,
    "inherited": true,
    "external": false
  },
  "searchInComments": true,
  "cleanOutputDir": true
}

NPM Scripts 配置 #

在 package.json 中添加脚本：

json

{
  "scripts": {
    "docs": "typedoc",
    "docs:watch": "typedoc --watch",
    "docs:serve": "typedoc --serve",
    "docs:json": "typedoc --json docs/api.json"
  }
}

运行：

bash

# 生成文档
npm run docs

# 监听模式（文件变化自动重新生成）
npm run docs:watch

# 启动本地服务器预览
npm run docs:serve

# 生成 JSON 格式
npm run docs:json

TypeScript 项目配置 #

tsconfig.json 基础配置 #

json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "lib": ["ES2020"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": true,
    "declarationMap": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

启用声明文件生成 #

json

{
  "compilerOptions": {
    "declaration": true,
    "declarationMap": true,
    "declarationDir": "./dist/types"
  }
}

Monorepo 项目配置 #

项目结构 #

text

monorepo/
├── packages/
│   ├── core/
│   │   ├── src/
│   │   │   └── index.ts
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── utils/
│   │   ├── src/
│   │   │   └── index.ts
│   │   ├── package.json
│   │   └── tsconfig.json
│   └── cli/
│       ├── src/
│       │   └── index.ts
│       ├── package.json
│       └── tsconfig.json
├── typedoc.json
├── package.json
└── tsconfig.json

根目录 typedoc.json #

json

{
  "entryPointStrategy": "packages",
  "entryPoints": [
    "packages/core",
    "packages/utils",
    "packages/cli"
  ],
  "out": "docs",
  "name": "Monorepo Documentation",
  "includeVersion": true,
  "excludePrivate": true,
  "excludeInternal": true
}

各包独立配置 #

json

// packages/core/typedoc.json
{
  "extends": ["../../typedoc.base.json"],
  "entryPoints": ["src/index.ts"],
  "name": "@myorg/core"
}

常见问题排查 #

1. 找不到模块 #

bash

# 错误信息
Error: Could not find module 'xxx'

# 解决方案：确保 tsconfig.json 正确配置
{
  "compilerOptions": {
    "moduleResolution": "node",
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

2. 类型解析错误 #

bash

# 错误信息
Error: Could not resolve type 'xxx'

# 解决方案：检查 tsconfig.json 的 include/exclude
{
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

3. 内存不足 #

bash

# 错误信息
JavaScript heap out of memory

# 解决方案：增加 Node.js 内存限制
export NODE_OPTIONS="--max-old-space-size=4096"
npx typedoc

4. 版本不兼容 #

bash

# 错误信息
peer dep missing: typescript@>=x.x.x

# 解决方案：更新 TypeScript 版本
npm install typescript@latest --save-dev

下一步 #

现在你已经完成了 TypeDoc 的安装和基本配置，接下来学习基本使用，了解更多关于编写文档注释的技巧！