企业官网建设流程全解析

• 开发工具
• 文档

本文以 TypeDoc 官方示例项目（example/目录）为主体，完整继承该示例 README 中的功能索引与示例组织方式，并结合示例工程的 TypeDoc 配置文件、package.json 脚本 与example/src/下的真实源码，讲解如何从零构建一个 TypeDoc 文档站点：包括构建命令、配置项逐项解读、文档注释（doc comment）的各种写法模式，以及各类 TypeScript 语言结构在文档中的呈现效果。读完后，你将掌握一套可直接复制到自己 TypeScript 项目中的文档工程化方案。

一、示例项目定位：TypeDoc 能做什么

example/README.md 开篇即给出 TypeDoc 的核心定位：它是 TypeScript 项目的文档生成器，自动为项目中导出的每一个变量、函数和类生成文档。开发者再通过 doc comment（文档注释）为 API 补充解释与示例。README 中给出的标准 doc comment 写法是：

/** * Calculates the square root of a number. * * @param x the number to calculate the root of. * @returns the square root if `x` is non-negative or `NaN` if `x` is negative. */ export function sqrt(x: number): number { return Math.sqrt(x); }

这段代码同时也是示例工程的真实源码（见 example/src/functions.ts），是理解 TypeDoc “摘要 + 参数 + 返回值”三段式文档注释的最小完整样本。

README 还明确列出了示例项目重点演示的三项能力：

• 对多种 TypeScript 语言结构的内建支持（内建语法构造支持）；
• doc comment 中的 Markdown 排版；
• 代码块中的语法高亮。

二、构建示例站点：五步命令流程

构建步骤完整记录在 example/building-the-example.md 中，共五步：

1. 在仓库根目录构建 TypeDoc：执行pnpm install和pnpm build；
2. 进入示例目录：cd example；
3. 在示例目录执行pnpm install（示例有独立的 package.json）；
4. 类型检查示例代码：pnpm tsc；
5. 生成文档：pnpm typedoc。

示例工程 package.json 中定义了三个 script，其中文档生成命令为：

"scripts": { "lint": "eslint .", "tsc": "tsc", "typedoc": "node ../bin/typedoc" }

typedoc脚本直接调用仓库根目录构建产物../bin/typedoc，说明该示例是配合 TypeDoc 源码一起开发的。依赖列表中包含了lodash、react、react-dom及对应@types包——这正对应了 README 功能索引中“以别名重新导出外部函数”（lodash）与“React 组件”（react）两类示例的存在前提。

配套的 example/tsconfig.json 采用ESNext目标与模块、strict: true、noEmit: true、jsx: react-jsx和experimentalDecorators: true等编译选项，文档生成依赖 TypeScript 语言服务做语义分析，因此一份能通过类型检查的 tsconfig 是生成准确文档的前提。

三、配置解析：example/typedoc.json 逐项解读

example/typedoc.json 是一份可直接借鉴的生产级配置，其全部字段如下：

{ "$schema": "https://typedoc.org/schema.json", "name": "TypeDoc Example", "entryPoints": ["./src"], "sort": ["source-order"], "categorizeByGroup": false, "searchCategoryBoosts": { "Component": 2, "Model": 1.2 }, "searchGroupBoosts": { "Classes": 1.5 }, "hostedBaseUrl": "https://typedoc.org/example/", "navigationLinks": { "Docs": "https://typedoc.org", "API": "https://typedoc.org/api/index.html", "GitHub": "https://github.com/TypeStrong/typedoc" }, "highlightLanguages": [ "typescript", "tsx", "css", "json", "jsonc", "python", "yaml", "markdown" ], "markdownItOptions": { "html": true }, "suppressCommentWarningsInDeclarationFiles": true }

各字段的作用说明：

其中entryPoints指向./src后，入口文件 example/src/index.ts 承担了“总装”角色：

/** * @packageDocumentation * @categoryDescription Component * React Components -- This description is added with the `@categoryDescription` tag * on the entry point in src/index.ts * * @document documents/external-markdown.md * @document documents/markdown.md * @document documents/syntax-highlighting.md * @document documents/include.md */ export * from "./classes"; export * from "./enums"; export * from "./functions"; export * from "./internals"; export * from "./reactComponents"; export * from "./reexports"; export * from "./types"; export * from "./variables";

这个入口注释集中展示了三个文档组织标签：@packageDocumentation提供包级说明；@categoryDescription为Component分类（对应配置中的searchCategoryBoosts.Component）补充分类描述；四个@document标签把 src/documents/ 下的外部 Markdown 文档（外部 Markdown 页、Markdown 排版展示页、语法高亮展示页、include 演示页）挂载进站点。@document引用的四个文档文件分别位于 external-markdown.md、markdown.md、syntax-highlighting.md 和 include.md。

四、README 功能索引：示例覆盖的七类场景

README 的“Index of Examples”指出：点击侧边栏的Exports链接可查看包内全部导出。在此之上，官方特意高亮了以下七类示例，这也是本文后续结合源码逐一剖析的骨架。

1. 渲染（Rendering）

• 外部 Markdown 文档：external-markdown.md
• Markdown 排版展示：markdown.md
• 语法高亮展示：syntax-highlighting.md

这三类演示 doc comment 与外部 Markdown 的渲染能力，其中语法高亮依赖配置中的highlightLanguages白名单。

2. 函数（Functions）

从源码中可以提炼出若干实用的文档注释模式：

箭头函数自动识别为函数：sqrtArrowFunction用const声明箭头函数，TypeDoc 会智能地将其按“函数”而非“变量”生成文档（见 functions.ts 的注释说明）。

泛型参数用@typeParam标注：concat<T>通过@typeParam T the element type of the arrays为类型参数补充说明。

options 对象两种写法：makeHttpCallA的选项类型定义为独立 interfaceMakeHttpCallAOptions，源码注释特别提醒“使用这种模式时务必导出 options 类型，否则 TypeDoc 不会为它生成文档”；makeHttpCallB则把对象类型直接内联在参数位置。两种写法 TypeDoc 都能渲染出带文档注释的属性表格。

重载签名：overloadedFunction声明了两组重载（number版与string版）加一个实现签名；站点上可以切换查看不同重载，且实现签名本身不进入文档——只有当某个重载没有 doc comment 时，TypeDoc 才会从实现签名复制注释。

重导出：reexports.ts 中一行export { sortBy as lodashSortBy } from "lodash"演示了第三方库函数改名为本地别名后再导出的文档化方式。

3. 类型（Types）

• 类型别名：SimpleTypeAlias与ComplexGenericTypeAlias
• 接口：User与AdminUser

对应源码 example/src/types.ts 中有三个值得注意的点：User接口演示了嵌套类型定义上的 doc comment——name属性内部的first/last字段各自带注释；AdminUser extends User演示了继承层级，站点会自动展示继承关系以及每个属性最初定义于哪个接口；ComplexGenericTypeAlias<T>是一个联合类型别名，覆盖T、T[]、Promise<T>、Promise<T[]>与Record<string, Promise<T>>五种形态，用于验证复杂泛型联合类型的渲染。

4. 类（Classes）

• 基础类：Customer（Customer.ts）
• 子类：DeliveryCustomer
• 复杂类：CancellablePromise
• 继承内建泛型类型的类：StringArray（StringArray.ts）

其中 CancellablePromise.ts 是全文档最复杂的示例类，展示了复杂方法签名、静态方法（resolve/reject/all/allSettled/race/delay）、以及static all上一个多达 10 组重载签名的方法。它的类级注释还演示了两个组织类标签：

• @typeParam T what the CancellablePromise resolves to：为类型参数T补充说明；
• @groupDescription Methods ...：为隐式生成的Methods分组添加描述，该描述会出现在列示分组的索引页；注释中同时说明@groupDescription对@group手动创建的分组和隐式分组均有效。

此外类中protected readonly promise属性演示了受保护成员的展示，cancel的注释说明“在promise已 resolved 之后调用cancel必须是 no-op”——参数与行为约束直接写进 doc comment 是 TypeDoc 推荐的 API 契约表达方式。

5. 枚举（Enums）

example/src/enums.ts 覆盖三种枚举形态：

• 基础枚举SimpleEnum：成员逐一写 doc comment（如Pending表示订单已下单未处理），混合了自动递增数值成员与显式字符串值成员Complete = "COMPLETE"；
• 含计算成员的CrazyEnum：注释明确说明“TypeDoc 不会显示计算成员的取值，因为该信息只在运行时可得”；
• 类枚举对象EnumLikeObject（以及数值版的EnumLikeObjectNumValues）：演示用as const对象模拟枚举的流行写法，并展示如何用@enum标签让 TypeDoc 把这类对象按枚举渲染。

6. 变量（Variables）

PI、STRING_CONSTANT、ObjectConstant三个常量覆盖了数字、字符串、对象字面量等常见常量形态，源码位于 example/src/variables.ts。

7. React 组件（React Components）

• 基础组件：CardA、CardB
• 复杂组件：EasyFormDialog与EasyFormDialogProps

源码位于 example/src/reactComponents.tsx。React 组件的 props 类型（如EasyFormDialogProps）是文档化的重点，配合入口index.ts上的@categoryDescription Component，组件类在站点导航中会被归入Component分类并享受searchCategoryBoosts中权重 2 的搜索加权。

五、把这套实践搬到自己的项目

综合上述示例工程，一个可直接套用的最小落地流程是：

1. 在项目中创建typedoc.json，至少指定entryPoints指向导出 API 的目录（参考 example/typedoc.json 中的./src）；
2. 入口文件中用@packageDocumentation写包级说明，按需使用@document挂载外部 Markdown 文档；
3. 遵循三段式 doc comment（摘要 /@param/@returns），泛型加@typeParam，类成员分组需要时用@group+@groupDescription；
4. 采用 options-object 参数风格时，把 options 类型单独定义为接口并导出，确保 TypeDoc 能收集到该类型的文档；
5. 需要类枚举（enum-like object）时加@enum标签；
6. 按需配置highlightLanguages、sort、searchCategoryBoosts等调优项；
7. 运行typedoc（示例中为pnpm typedoc，即node ../bin/typedoc）生成站点，通过侧边栏Exports链接核对导出清单的完整性。

小结

example/目录是 TypeDoc 官方维护的“活文档”：它既是一份功能索引（README 的七类示例），又是一套真实可构建的 TypeDoc 配置与注释规范样板（typedoc.json、index.ts、functions.ts、enums.ts、CancellablePromise.ts）。按照 building-the-example.md 的五步流程构建后，即可对照本文逐节验证每种 TypeScript 构造与文档标签在最终站点中的呈现效果，作为自己项目文档化方案的设计参照。

• 开发工具
• 文档