Storybook Angular 接入 Compodoc：自动生成组件文档与 Controls 的完整配置指南

2026-09-06 19:19:29作者：姚月梅Lane

Storybook 的 Angular 框架通过内置的 Compodoc 集成，可以从组件源码中的 JSDoc 注释自动生成 documentation.json，并以此驱动 Controls 面板与自动文档（Autodocs）的展示。本文以 angular-add-compodoc.md 与 Angular 官方接入文档为核心，结合仓库源码，完整讲解在 Angular 项目中启用 Compodoc 的安装、Builder 配置、preview 接线三大步骤，并深入说明其底层数据流。读完本文，你将能够在自己的 Angular + Storybook 项目中一键复现这套文档生成链路。

一、Compodoc 集成解决什么问题

在 Angular 组件开发中，开发者通常会围绕组件属性维护两类信息：@Input / @Output 的类型与含义，以及组件的使用文档。这些信息分散在源码注释里，容易与 UI 展示脱节。Storybook 的 Angular 框架将 Compodoc 构建进工作流，实现「注释即文档」：

当你在组件、指令、管道上方的注释中书写 JSDoc，并重点为 @Input、@Output 补充说明时；
Compodoc 会把这些信息序列化到一份 documentation.json；
Storybook 的预览端读取该 JSON，在 Controls 面板 渲染可交互的控件，并在 Docs / Autodocs 页面 生成组件参数表。

从源码结构看，这套能力分成三段独立代码：Builder 侧负责“跑 Compodoc 出 JSON”（run-compodoc.ts），预览端入口负责“接收 JSON”（addons/docs/src/angular/index.ts），而解析/提取逻辑收敛在共享包 @storybook/angular-compodoc（browser.ts）。下文按三段链路逐步配置。

二、安装 @compodoc/compodoc

首先在 Angular 项目中将 Compodoc 安装为开发依赖。官方提供 npm / pnpm / yarn 三种包管理器命令（见 compodoc-install.md）：

# npm
npm install @compodoc/compodoc --save-dev

# pnpm
pnpm add --save-dev @compodoc/compodoc

# yarn
yarn add --dev @compodoc/compodoc

安装后无需在 package.json 中手动串联 compodoc 命令：Storybook 的 Angular Builder 已把执行逻辑内置，你只负责开启选项（见下一节）。官方文档特别提醒，如果你此前用 "docs:json": "compodoc -p tsconfig.json -e json -d ./documentation" 之类的脚本手动生成，迁移到 Builder 方案后可以安全删除相关 script，避免重复运行。

三、在 angular.json 中开启 Compodoc

以 Angular Workspace 为标准场景，在 angular.json 里项目级 architect 的 storybook 与 build-storybook 两个 target 上同时开启两个选项：

{
  "projects": {
    "your-project": {
      "architect": {
        "storybook": {
          "builder": "@storybook/angular:start-storybook",
          "options": {
            // 👇 Add these
            "compodoc": true,
            "compodocArgs": [
              "-e",
              "json",
              "-d",
              // Where to store the generated documentation. It's usually the root of your Angular project.
              // It's not necessarily the root of your Angular Workspace!
              "."
            ]
          }
        },
        "build-storybook": {
          "builder": "@storybook/angular:build-storybook",
          "options": {
            // 👇 Add these
            "compodoc": true,
            "compodocArgs": ["-e", "json", "-d", "."]
          }
        }
      }
    }
  }
}

3.1 选项语义与默认行为

配置项	含义
`"compodoc"`	是否在启动/构建 Storybook 之前执行 Compodoc。取 `true` 时，每次运行都会重新生成 `documentation.json`
`"compodocArgs"`	透传给 `@compodoc/compodoc` CLI 的参数数组，例如 `["-e", "json"]`

关键细节藏在默认值的补全逻辑里，可以对照 run-compodoc.ts 源码确认：

-p（tsconfig 路径）：若你的 compodocArgs 中没有提供 -p，Builder 会自动追加项目当前的 tsconfig 路径；提供则尊重你的值。
-d / --output（输出目录）：若你的 compodocArgs 中没有提供，Builder 会自动追加工作区根目录（context.workspaceRoot）；上面示例显式给出 -d . 属于常规写法。
-e（导出格式）：json 表示只输出 JSON 供 Storybook 使用；文档说明也强调，需要 Compodoc 的浏览器可读 HTML 站点时应另行单独调用 Compodoc 生成。
相对路径：为避免 Windows 上绝对路径问题，源码会对 tsconfig 做一次 relative('.', ...) 转换后再传给 Compodoc。

Builder 会通过包管理器执行 compodoc，并附带任务状态输出（Generating documentation with Compodoc / Compodoc finished successfully）。同一参数的端到端调用可以在 start-storybook 的测试用例中看到，例如期望生成 ['compodoc', '-p', './storybook/tsconfig.ts', '-d', '.', '-e', 'json'] 这样的命令序列。

说明：以上两个选项同样适用于 Vite 版框架 @storybook/angular-vite，但在该框架默认启用 experimentalDocgenServer 特性的新管线中不再生效（详见第六节）。

3.2 自动安装路径

如果你是在已有 Storybook 项目之外从零开始，更省事的方式是直接执行：

npx storybook@latest init

init 会自动探测 Angular 项目并询问是否配置 Compodoc，帮你完成上述 angular.json 写入；随后的版本升级也可用 npx storybook@latest automigrate 自动修复/迁移相关配置。

四、在 preview 中注入 documentation.json

angular.json 只负责“生成 JSON”，真正让 Storybook 预览端读取 JSON 的是 .storybook/preview.ts 里的 setCompodocJson 调用——这正是 angular-add-compodoc.md 这个代码片段所演示的内容。

4.1 CSF 3 写法

import type { Preview } from '@storybook/angular';

// 👇 Add these
import { setCompodocJson } from '@storybook/addon-docs/angular';
import docJson from '../documentation.json';
setCompodocJson(docJson);

const preview: Preview = {
  // ...
};

export default preview;

4.2 CSF Next（实验特性）写法

新版框架同时支持以 definePreview 声明预览配置的写法，接线逻辑完全相同：

import { definePreview } from '@storybook/angular';

// 👇 Add these
import { setCompodocJson } from '@storybook/addon-docs/angular';
import docJson from '../documentation.json';
setCompodocJson(docJson);

const preview = definePreview({
  // ...
});

export default preview;

4.3 三个容易踩坑的路径问题

documentation.json 的存放位置：默认生成在 Angular 项目根目录（也就是 compodocArgs 中 -d 指向的目录），它不一定是 Angular Workspace 根目录。上面的 import 路径 ../documentation.json 以 .storybook/ 为相对起点，请根据你的实际目录结构调整。
输出目录一致性：请确保 compodocArgs 里的 -d 与你 import 的路径一致，否则会出现“JSON 已生成但 preview 读到旧文件”的错觉。
执行时机：setCompodocJson 只在预览启动时执行一次；因此 Builder 每次运行 Storybook 前都会重新生成 documentation.json，保证注释改动即时生效。

五、底层数据流：从 JSON 到 Controls 与 Docs

理解 setCompodocJson 做了什么，有助于排查“面板没内容”的问题。逐层看源码：

写入全局。setCompodocJson 把 JSON 挂到 global.__STORYBOOK_COMPODOC_JSON__ 上。旧版入口见 addons/docs/src/angular/index.ts：
```
export const setCompodocJson = (compodocJson: any) => {
  (globalThis as any).__STORYBOOK_COMPODOC_JSON__ = compodocJson;
};
```
消费读取。共享适配器 browser.ts 定义配套的 getCompodocJson，返回 global.__STORYBOOK_COMPODOC_JSON__。
提取参数类型。@storybook/angular 客户端模块（compodoc.ts）再从 @storybook/angular-compodoc/browser 导出 extractArgTypes、extractComponentDescription、findComponentByName、checkValidCompodocJson 等工具；Controls 与 Docs 的参数表本质上由这些函数基于同一份 Compodoc JSON 计算得到。

因此整条链路是：JSDoc 注释 → Compodoc（Builder 触发）→ documentation.json → setCompodocJson 挂全局 → extractArgTypes 等工具消费 → Controls / Docs 渲染。任一环节断裂都会表现为“文档缺失”，排查时可按此顺序定位。

5.1 需要写什么样的注释

文档明确建议：把解释性注释写在组件中 Storybook 会展示的元素上，尤其是 @Input 与 @Output——它们正是用户能在 UI 中通过 Controls 交互的部分。例如：

@Component({ selector: 'app-button', ... })
export class ButtonComponent {
  /** 按钮的主文案 */
  @Input() label = '';
  /** 点击后是否禁用 */
  @Input() disabled = false;
  /** 点击事件 */
  @Output() clicked = new EventEmitter<void>();
}

这类注释会以参数表/描述的形式出现在 Autodocs 与 Controls 中，是 Compodoc 集成最直接的收益点。

六、兼容性边界：Vite 框架与 experimentalDocgenServer

仓库当前同时维护两套 Angular 框架，Compodoc 的适用前提有所不同，需要区分清楚，避免配置后“无效”：

@storybook/angular（Webpack 版，Builder 为 @storybook/angular:start-storybook / build-storybook）：本文的完整配置链路原生生效，这是 Compodoc 集成的主阵地。
@storybook/angular-vite：该框架的默认文档生成走服务端 experimentalDocgenServer 新管线，不再读取 Compodoc 产物。此时 setCompodocJson 会静默返回并打印一次会话级警告（源码见 index.ts），提示可以删除该调用与 documentation.json 的 import。
若你在 angular-vite 项目中通过关闭 experimentalDocgenServer 回到 Compodoc 旧管线，那么第六节之前的所有配置依然可用；但该兼容路径已在路线图中标注为未来废弃（计划在 Storybook 12 移除），仅建议作为迁移过渡手段。

因此，无论你从哪篇教程拷贝代码，都应先确认自己用的是 @storybook/angular 还是 @storybook/angular-vite，再决定是否需要 setCompodocJson。

七、小结

在 Storybook Angular 项目中启用 Compodoc 只需记住三步：安装 @compodoc/compodoc；在 angular.json 的 storybook 与 build-storybook target 上开启 "compodoc": true 并给出 compodocArgs；在 .storybook/preview.ts 中调用 setCompodocJson 注入生成的 documentation.json。三步之后，组件上的 JSDoc 注释就会自动演化为 Controls 面板和 Docs 文档，而它的执行细节——默认参数补全、全局 JSON 存储、以及 Webpack/Vite 两套框架的差异——都可以在仓库的 run-compodoc.ts、angular-compodoc browser 适配器与 docs 框架接入文档中进一步核对与验证。