企业官网建设流程全解析

Storybook 手动接入 Angular：在.storybook/main.ts中配置@storybook/angular框架

【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook

本篇指南讲解如何在 Storybook 的配置入口.storybook/main.ts中声明@storybook/angular框架，并在此基础上完成 Angular CLI builder 的配套接入，实现用ng run驱动 Storybook 的开发与构建。这是对官方 Angular 集成文档中「手动安装 Angular 框架」一节（参见 docs/get-started/frameworks/angular.mdx）与代码片段 angular-add-framework.md 的完整解读，读者完成阅读后能够掌握 framework 字段的两种写法（CSF 3 与 CSF Next）、两种配置风格下类型来源的差异，以及让 Storybook 跑在 Angular CLI 工作区中所需的全部配置步骤。

为什么需要在main.ts中添加 framework 字段

Storybook 的main.ts是其核心配置文件，用于声明「在哪个框架（React / Vue / Angular / Svelte…）之上构建组件预览」。对于 Angular 项目而言，将framework指向@storybook/angular意味着：

• 使用 Storybook 官方提供的 Angular renderer 渲染组件与 story；
• 加载配套的 Angular server presets（见 framework-preset-angular-cli.ts 与 framework-preset-angular-ivy.ts），负责接入 Angular CLI 的编译链与 Compodoc 文档生成；
• 获得与 Angular 强类型相关的StorybookConfig类型提示。

官方文档在「手动安装 Angular 框架」FAQ 中给出了完整三步：安装依赖、改写main.ts、补全angular.jsonbuilder。本文中的核心代码片段正是其中的第二步。

在.storybook/main.ts中声明@storybook/angular

@storybook/angular的当前源码版本为10.6.0-beta.1（见 package.json）。配置主文件有两种写法，官方文档片段 angular-add-framework.md 同时给出了两种，可按项目采用的主文件风格选择。

写法一：CSF 3 风格

import { StorybookConfig } from '@storybook/angular'; const config: StorybookConfig = { // ... framework: '@storybook/angular', // 👈 Add this }; export default config;

写法二：CSF Next（实验性）风格

import { defineMain } from '@storybook/angular/node'; export default defineMain({ // ... framework: '@storybook/angular', // 👈 Add this });

从源码来看，defineMain是一个返回原配置的恒等包装函数，仅用于提供类型约束与更严格的配置校验：

// code/frameworks/angular/src/node/index.ts export function defineMain(config: StorybookConfig) { return config; }

因此defineMain与StorybookConfig两种写法在类型层面是等价的——区别只是后者通过函数入口集中导入了StorybookConfig类型。值得注意的是，@storybook/angular包通过exports字段同时暴露了主入口与./node子路径（见 package.json），defineMain只能从@storybook/angular/node导入。

framework 字段的类型约束

从 types.ts 可以看到，StorybookConfig中的framework字段是联合类型，既可以是简写字符串，也可以是携带options的完整对象：

export type FrameworkOptions = AngularOptions & { builder?: BuilderOptions; }; type StorybookConfigFramework = { framework: | FrameworkName // '@storybook/angular' | { name: FrameworkName; options: FrameworkOptions; }; // ... };

这意味着你还可以在main.ts中传递框架级配置对象（例如options.enableIvy），完整形态见代码片段 angular-framework-options.md：

import type { StorybookConfig } from '@storybook/angular'; const config: StorybookConfig = { framework: { name: '@storybook/angular', options: { // ... }, }, }; export default config;

AngularOptions目前定义的字段为enableIvy（参见 types.ts），用于关闭 Ivy 编译等旧版本兼容场景；在如今的 Angular 17+ 项目中通常无需设置。

前置步骤：安装框架依赖

在改写main.ts之前，需要先在项目根目录把框架安装为开发依赖。官方文档 angular-install.md 给出了三种包管理器的等价命令：

npm install --save-dev @storybook/angular

pnpm add --save-dev @storybook/angular

yarn add --dev @storybook/angular

版本约束方面，当前仓库的@storybook/angular将@angular/*、@angular-devkit/*声明为peerDependencies，范围均为>=18.0.0 < 23.0.0（见 package.json），与文档标注的支持范围（Angular ≥ 18 < 23、Webpack 5）一致。安装前请确认你的 Angular 版本处于该区间内。

配套配置：在angular.json中挂接 Storybook builder

只改main.ts还不能在 Angular CLI 工作区中运行 Storybook。手动安装流程的最后一步是更新angular.json，为项目注册storybook与build-storybook两个 architect target。官方文档给出了如下完整示例：

{ "projects": { "your-project": { "architect": { "storybook": { "builder": "@storybook/angular:start-storybook", "options": { // The path to the storybook config directory "configDir": ".storybook", // The build target of your project "browserTarget": "your-project:build", // The port you want to start Storybook on "port": 6006, }, }, "build-storybook": { "builder": "@storybook/angular:build-storybook", "options": { "configDir": ".storybook", "browserTarget": "your-project:build", "outputDir": "dist/storybook/your-project", }, }, }, }, }, }

这两个 builder 的完整可选字段由包内两个 JSON Schema 定义：start-schema.json（对应@storybook/angular:start-storybook）与 build-schema.json（对应@storybook/angular:build-storybook），运行时会由@angular-devkit/architect读取校验。

完成注册后，将package.json中的脚本替换为 Angular CLI 命令即可统一用ng run管理：

{ "scripts": { - "storybook": "start-storybook -p 6006", // or `storybook dev -p 6006` - "build-storybook": "build-storybook" // or `storybook build` + "storybook": "ng run <project-name>:storybook", + "build-storybook": "ng run <project-name>:build-storybook", } }

注意：compodoc已被内置于@storybook/angularbuilder 中，不再需要像旧版那样在脚本里先手动执行compodoc再启动 Storybook。如果你的package.json中还存在docs:json、storybook串联 compodoc 的旧脚本，可以直接删除。

builder 常用配置项速查

对于多项目工作区或需要精细控制启动行为的场景，官方文档在 angular.mdx 中汇总了 builder 常见选项，此处精选高频配置说明：

多项目工作区的处理方式

如果你的 Angular workspace 中存在多个项目，则需要对每个要使用 Storybook 的项目分别执行上述angular.json与package.json配置。官方推荐：

1. 每个项目在自身根目录下拥有独立的.storybook文件夹；
2. 为每个项目依次运行npx storybook@latest init，由 CLI 自动创建.storybook目录并写入angular.json的 builder 配置；
3. 如需在单个界面查看多个 Storybook，可通过 Storybook composition 把多个实例组合起来。

npx storybook@latest automigrate则用于让 Storybook 自动检测并修复既有配置（例如把旧的start-storybook -p 6006脚本迁移为ng run形式的 Angular builder）。

framework 在构建链路中如何被消费

framework字段并非仅仅是一个“标签”。当 Storybook 在 Angular 项目中启动时，framework-preset-angular-ivy.ts 会主动读取预设中的 framework 配置以决定 Angular 相关编译行为：

// code/frameworks/angular/src/server/framework-preset-angular-ivy.ts const framework = await options.presets.apply<Preset>('framework'); const angularOptions = (typeof framework === 'object' ? framework.options : {}) as AngularOptions;

可以看到该 preset 对 framework 字段做了「字符串 or 对象」两种形态的兼容解析——这正好呼应了上一节StorybookConfig类型中framework联合类型的定义：无论你在main.ts中写framework: '@storybook/angular'还是对象形态，底层都会正确识别，只是对象形态还能携带options（如enableIvy）。因此从源码层面可以确认：framework 声明是后续所有 Angular 专用预设、builder 与 Compodoc 集成能否正确加载的前提。

运行验证

配置完成后，在项目根目录执行：

ng run <your-project>:storybook

即可启动开发模式；执行：

ng run <your-project>:build-storybook

可产出静态构建，产物默认位于dist/storybook/<your-project>（受outputDir控制）。启动成功后，浏览器将打开http://localhost:6006（或你配置的port/host）。

相关资源与延伸阅读

• 本文主体代码片段：angular-add-framework.md
• 框架安装命令：angular-install.md
• 框架 options 对象写法：angular-framework-options.md
• 官方 Angular（Webpack）框架指南：docs/get-started/frameworks/angular.mdx，其中包含 builder 全量配置表、Compodoc 手动集成、applicationConfig/moduleMetadata装饰器示例
• Angular 框架源码目录：code/frameworks/angular，重点可看类型定义 types.ts、builder schema（start-schema.json、build-schema.json）以及两个 server preset
• 若你使用的是Angular ≥ 21且希望获得更快的构建速度并启用 Vitest 测试插件，官方建议改用基于 Vite 的同级框架@storybook/angular-vite，其切换方式（将import与framework由@storybook/angular改为@storybook/angular-vite）参见 docs/get-started/frameworks/angular-vite.mdx。

【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook