Storybook 中安装 @storybook/angular-vite：npm / pnpm / yarn 安装命令与接线实战

@storybook/angular-vite 是 Storybook 官方为 Angular 提供的、基于 Vite 构建链路的框架包。本文以仓库中实际使用的安装片段 docs/_snippets/angular-vite-install.md 为主线，讲解三种包管理器下的精确安装命令、安装前的版本要求、安装后如何在 .storybook/main.ts 中完成接线，以及该片段在官方文档（如“从 @storybook/angular 手动迁移”）中的真实使用场景。读完本文，你可以独立完成一个 Angular 21+ 项目到 @storybook/angular-vite 的安装与验证，并能对照包依赖结构理解“安装这个包到底往项目里引入了什么”。

这个包解决什么问题

@storybook/angular-vite 在包的官方描述中定位为：

Storybook for Angular: Develop, document, and test UI components in isolation（参见 code/frameworks/angular-vite/package.json 的 description 字段）。

它是与 Webpack 5 版 @storybook/angular 平级的另一套 Angular 框架选项。根据官方框架指南 docs/get-started/frameworks/angular-vite.mdx 的描述，选用它通常基于以下动机：

• 相比 Webpack 版本获得更快的构建与 HMR 体验；
• 完整支持 Vitest addon 与浏览器内的组件测试（因为整套链路都是 Vite）；
• 配置更简单，不依赖 Babel，依赖体积更小。

值得留意的是，该框架文档明确提示：当前仍处于 preview 状态，计划在 Storybook 11 中转为 stable（见 docs/get-started/frameworks/angular-vite.mdx 顶部的 Callout），使用前请确认你对 API 可能变化的接受度。

安装前的前置要求：先核对版本矩阵

不要跳过版本核对直接执行安装命令。@storybook/angular-vite 的 peerDependencies 非常严格，版本不匹配会在安装或启动阶段暴露问题。

从 docs/get-started/frameworks/angular-vite.mdx 的 “Requirements” 与 FAQ 可以确认两硬性下限：

依赖	最低/范围要求	说明
Angular	≥ 21	FAQ 明确指出 Angular 20 及更早版本不支持，请继续使用 Webpack 版 @storybook/angular
Vite	≥ 8	构建链路依赖较新的 Vite 版本

而在包的 code/frameworks/angular-vite/package.json 中，peerDependencies 给出了更精确的区间：

• @angular/*（core、compiler、compiler-cli、common、platform-browser、animations 等）：>=21.0.0 < 23.0.0；
• @angular/build：>=21.0.0 < 23.0.0；
• @analogjs/vite-plugin-angular：>= 2.0.0（Angular 的 Vite 转换管线由 AnalogJS 插件驱动）；
• vite：>=8.0.0；
• typescript：>= 5.9.x；
• rxjs：^7.4.0；
• storybook：同仓库的 workspace:^（发布后即与 storybook 主包同版本范围）。

其中 @angular/cli 与 zone.js 被标记为可选 peer 依赖（peerDependenciesMeta），意味着纯 CLI 工作流与 zoneless 模式下并非强依赖。

核心安装命令：三种包管理器逐一对应

以下是 docs/_snippets/angular-vite-install.md 中记录的完整安装命令。它们是同一操作的三种包管理器等价写法，安装目标是相同的 @storybook/angular-vite 包：

npm

npm install --save-dev @storybook/angular-vite

pnpm

pnpm add --save-dev @storybook/angular-vite

yarn

yarn add --dev @storybook/angular-vite

要点说明：

• 三条命令全部把包写入 devDependencies（--save-dev / -D / --dev）。这是符合预期的：Storybook 及其框架只参与开发、调试与测试，不应进入生产构建产物；
• 三者不要同时执行。请根据你项目既有的包管理器选择其一，并保证之后始终用同一管理器，避免 lockfile 混用产生依赖树不一致；
• 命令应在项目根目录（即包含 package.json 的目录）下执行；
• 如果你正在使用 Storybook 的自动初始化流程（npm create storybook@latest，见 docs/_snippets/create-command.md），CLI 会自动完成等价安装；上述命令主要面向“现有项目手动安装 / 迁移框架”的场景，它是官方文档中手动迁移路径的第一步。

安装进项目的东西：一个框架预设 + 一套 Angular CLI builders

从 code/frameworks/angular-vite/package.json 的 exports 字段可以清晰看出，这个包并不仅仅是“另一个渲染器”，它对外同时提供：

• ./preset：Storybook 的框架预设入口，负责注入 Vite builder 相关配置（@storybook/builder-vite 是其直接依赖）；
• ./builders/start-storybook 与 ./builders/build-storybook：Angular CLI builder 实现，使你能用 ng run 启动/构建 Storybook；
• ./client、./client/config、./client/docs/config：preview 运行时与 docs 配置；
• ./node：面向 Node 侧的类型与配置助手（如 CSF Next 的 defineMain）；
• ./vitest：暴露 storybookAngularVitest，用于在独立 vitest 进程里把 Angular 构建选项（styles、assets、zoneless 等）桥接给框架读取。

也就是说，安装命令执行成功后，你同时获得了“Vite 构建的 Storybook 框架”与“Angular 工作区里可注册的 architect builder”两条使用路径。仓库中这两条路径的 schema 分别定义在 code/frameworks/angular-vite/start-schema.json 与 code/frameworks/angular-vite/builders.json 中。

安装后的接线：在 .storybook/main.ts 中切换框架

仅仅安装包还不够，Storybook 需要知道“用哪个框架”来驱动预览。修改 .storybook/main.ts，把 framework 指向新包，并同步替换类型导入来源（CSF 3 写法）：

- import type { StorybookConfig } from '@storybook/angular';
+ import type { StorybookConfig } from '@storybook/angular-vite';

 const config: StorybookConfig = {
   // ...
-  framework: '@storybook/angular',
+  framework: '@storybook/angular-vite',
 };

 export default config;

若项目使用 CSF Next（defineMain），则从 Node 侧子路径导入：

- import { defineMain } from '@storybook/angular/node';
+ import { defineMain } from '@storybook/angular-vite/node';

 export default defineMain({
   // ...
-  framework: '@storybook/angular',
+  framework: '@storybook/angular-vite',
 });

上述两段完整 diff 均来自配套片段 docs/_snippets/angular-vite-add-framework.md。

框架切换后，一个可见的行为差异是组件文档的读取引擎：@storybook/angular-vite 默认开启 experimentalDocgenServer，直接在 Storybook 服务端读取你的 TypeScript 源码生成 controls、autodocs 与代码片段，不再依赖 Compodoc 生成 documentation.json（详见 docs/get-started/frameworks/angular-vite.mdx 的 “Component documentation” 一节）。

运行验证：Storybook CLI 与 Angular CLI 两条路径

安装并接线后，可通过两条路径验证安装是否成功。

路径一：Storybook CLI（推荐用于快速验证）

# 启动开发模式
npx storybook dev

# 构建静态站点
npx storybook build

构建产物默认输出到 storybook-static（可用 outputDir 调整）。

路径二：Angular CLI builders

在 angular.json 的 architect 中注册两个 builder：

{
  "projects": {
    "your-project": {
      "architect": {
        "storybook": {
          "builder": "@storybook/angular-vite:start-storybook",
          "options": {
            "configDir": ".storybook",
            "port": 6006,
          },
        },
        "build-storybook": {
          "builder": "@storybook/angular-vite:build-storybook",
          "options": {
            "configDir": ".storybook",
            "outputDir": "dist/storybook/your-project",
          },
        },
      },
    },
  },
}

随后通过 ng run your-project:storybook 与 ng run your-project:build-storybook 运行。

这里有一个与 Webpack 版框架的关键区别（也是迁移时必须注意的点）：@storybook/angular-vite 的 builders 不接受 browserTarget。由于 Vite 直接解析项目的 TypeScript 与静态资源，无需引用 Angular 的构建目标，配置里应删除 browserTarget 项。

实际使用场景：从 @storybook/angular 手动迁移

安装片段 docs/_snippets/angular-vite-install.md 在官方文档中并非孤立出现——它被作为 CodeSnippets 引入 docs/get-started/frameworks/angular-vite.mdx 的 Manual migration（手动迁移） 章节，作为迁移流程的第一步：

1. 先安装框架包：执行本文开头给出的三条命令之一；
2. 修改 .storybook/main.ts 的 framework（即上文接线步骤）；
3. 若 angular.json 已声明 Storybook architect targets，把 builder 引用从 @storybook/angular:* 改为 @storybook/angular-vite:*，并删除 browserTarget；
4. 将 webpackFinal 钩子迁移为 viteFinal；
5. 对直接以字符串形式导入的 Markdown 文件，在导入路径追加 Vite 的 ?raw 后缀。

如果你希望全程自动化，也可以先执行 npx storybook automigrate 走自动迁移路径，但自动化无法替你改写 webpackFinal 钩子和 .md 直接导入两件事。

对于从 Compodoc 体系升级的老项目，官方同样推荐默认路径而非继续配置 Compodoc：setCompodocJson 在默认路径下不存储任何数据并仅记录一次性警告，遗留的 documentation.json 导入不会污染 controls 表。

常见误区与核对清单

安装这个包前后，请对照以下清单逐项自查，避免把时间浪费在环境问题上：

• [ ] 项目 Angular 版本 ≥ 21（@angular/core 过低请改回 @storybook/angular）；
• [ ] 项目 Vite 版本 ≥ 8，TypeScript ≥ 5.9.x；
• [ ] 三条安装命令只执行了一条，且落入了 devDependencies；
• [ ] .storybook/main.ts 中 framework 与类型导入都已指向 @storybook/angular-vite；
• [ ] 若使用 Angular builders：删除了 browserTarget，builder 前缀为 @storybook/angular-vite:；
• [ ] 若存在 webpackFinal：已迁移为 viteFinal（Vite 不会读取 tsconfig.json 的 paths，路径别名需通过 vite-tsconfig-paths 插件或 resolve.alias 显式注册）；
• [ ] 运行时确认启动无 framework 相关报错，并能正常渲染现有 CSF stories。

完成以上步骤后，你的 Angular 项目即可获得基于 Vite 的 Storybook 开发与测试链路，并可直接接入 Vitest addon 开展组件测试。若想进一步了解该框架的完整配置项（如 jit、tsconfig、zoneless、compodoc 等），请继续阅读 docs/get-started/frameworks/angular-vite.mdx 的 API 章节。