Storybook 框架安装实战：为 Next.js 项目接入 @storybook/nextjs-vite（npm / pnpm / yarn 三种方式）

2026-09-07 17:12:29作者：沈韬淼Beryl

本文围绕 Storybook 文档中的安装片段 nextjs-vite-install.md 展开，讲解如何把 @storybook/nextjs-vite 框架包安装进现有 Next.js 项目，并回答“装的是什么、装完配什么、配完怎么跑”三个问题。读完后你能独立完成该框架的安装、.storybook/main.js|ts 配置切换，并理解这个包内部为 Next.js 提供的构建插件与模块 mock 能力。

这个片段在 Storybook 文档中的位置

@storybook/nextjs-vite 的安装命令被引用在官方框架文档 Next.js (Vite) 页面的 “Manual migration”（手动迁移）小节中，即从 Webpack 版框架 @storybook/nextjs 迁移到 Vite 版框架时的第一步：先安装框架包，再修改 framework 配置。

在官方文档的定位中，Next.js (Vite) 是 Next.js 应用开发、文档化和测试 UI 组件的推荐框架，相比 Webpack 版的 @storybook/nextjs，它的优势包括：

更快的构建：Vite 构建系统显著快于 Webpack；
更现代的工具链：使用最新构建工具与优化；
更好的测试支持：完整支持 Vitest addon 与其他测试特性；
更简单的配置：无需 Babel 或复杂的 Webpack 配置；
更好的开发体验：更快的 HMR 与 dev server 启动。

此外，执行 storybook init 时，Storybook 会自动探测项目并优先选择 nextjs-vite 框架，除非项目存在自定义的 Webpack 或 Babel 配置——此时 CLI 会询问你选择哪个框架。因此理解手动安装，对“自动初始化选了 Webpack 版”或“存量项目要迁移”两类场景都很有价值。

安装命令：npm、pnpm、yarn 三种包管理器

官方安装片段 nextjs-vite-install.md 按包管理器提供了三条等价命令，在项目根目录执行即可：

# npm
npm install --save-dev @storybook/nextjs-vite

# pnpm
pnpm add --save-dev @storybook/nextjs-vite

# yarn
yarn add --dev @storybook/nextjs-vite

三条命令的语义一致：把 @storybook/nextjs-vite 作为开发依赖（devDependencies）写入 package.json。它不会被打包进你的 Next.js 应用，只在开发、文档化与测试组件时使用，因此放入 dev 依赖是正确的做法。

安装前提：版本要求

文档在框架页面中声明的版本要求如下：

依赖	要求
Next.js	≥ 14.1
Vite	≥ 5

从当前仓库源码 code/frameworks/nextjs-vite/package.json 中的 peerDependencies 可以看到更精确的取值范围，可作为安装前自查的依据：

next: ^14.1.0 || ^15.0.0 || ^16.0.0；
vite: ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0；
react / react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0；
@types/react 与 @types/react-dom 为可选 peer 依赖（optional: true）。

也就是说，如果你的 Next.js 项目停留在 14.1 以下，或 Vite 版本过低，需要先升级宿主项目再安装本框架。该包本身的依赖关系同样写在 package.json 中：它内部复用了 @storybook/builder-vite、@storybook/react、@storybook/react-vite、vite-plugin-storybook-nextjs，以及固定版本的 styled-jsx@5.1.6——这解释了文档中“styled-jsx 零配置支持”的出处（源码目录 code/frameworks/nextjs-vite/src/styledJsx）。

装完后做什么：配置 framework 并运行

安装只是第一步，还需要在 .storybook/main.js 或 .storybook/main.ts 中把 framework 指向新框架。官方文档给出的手动迁移步骤（见 Next.js (Vite) 页面的 Manual migration 小节）对应的配置片段为 nextjs-vite-add-framework.md，其核心变更如下：

export default {
  // ...
-  framework: '@storybook/react-webpack5',
+  framework: '@storybook/nextjs-vite',
};

- import type { StorybookConfig } from '@storybook/your-previous-framework';
+ import type { StorybookConfig } from '@storybook/nextjs-vite';

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

export default config;

对于新实验性的 defineMain 配置风格，则从 @storybook/nextjs-vite/node 子路径导入：

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

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

两个容易踩的迁移注意点（文档 Callout 原文强调）：

若旧配置里用 webpackFinal 做过自定义 Webpack 操作，需要在 Vite 侧用 viteFinal 重新表达；
直接 .md 文件导入在 Webpack 下默认可用，迁到 Vite 后需要加 ?raw 后缀。

如果之前还安装了针对 Next.js 的 Storybook 插件式 addon，切换本框架后这些已不再必要，可以移除。

配置完成后即可运行：yarn storybook dev 启动开发服务器，yarn build-storybook 构建静态产物（默认输出到 storybook-static，可通过 outputDir 配置修改）。

不想手动改配置的，也可以用官方提供的自动化迁移命令（同样来自框架文档的 FAQ）：

npx storybook automigrate nextjs-to-nextjs-vite

该自动化工具会执行三件事：把 package.json 中的 @storybook/nextjs 替换为 @storybook/nextjs-vite、更新 .storybook/main.js|ts 的 framework 属性、扫描并改写 story 文件与配置文件中的 import 语句。

从源码看：这个包安装进来后提供了什么

从 code/frameworks/nextjs-vite/package.json 的 exports 字段可以精确看出该包的公开子入口，这也是“安装后能用哪些 API”的权威清单：

子路径	用途
`.`（默认）	框架主入口，供 `framework: '@storybook/nextjs-vite'` 解析
`/node`	Node 侧入口，提供 `defineMain` 等配置能力
`/preset`	Storybook 框架 preset（见 preset.js 与 src/preset.ts）
`/preview`	预览侧入口（src/preview.tsx），注入 Next.js 运行时 mock
`/cache.mock`、`/headers.mock`、`/navigation.mock`、`/router.mock`	内置的 Next.js 内部模块 mock（源码位于 src/export-mocks）
`/vite-plugin`	供 `viteFinal` 复用的 Vite 插件能力

内置 mock 与源码目录结构相互印证。从 code/frameworks/nextjs-vite/src 的目录结构看，框架把 Next.js 的运行时能力拆成了若干可维护模块：

routing/ 与 export-mocks/：stub next/router（pages 目录）与 next/navigation（app 目录），文档说明所有路由交互会被记录到 Actions 面板，且 push()、replace() 等方法都是可用标准 mock API 断言的 mock 函数；
head-manager/：支持 next/head，Head 的 children 会被放入 Storybook iframe 的 <head> 元素；
styledJsx/：零配置支持 Next.js 内置 CSS-in-JS；
images/：让 next/image 免配置使用，本地图片导入会自动提供 width/height；
vite-plugin/ 与 config/：承接 Vite 配置合并、PostCSS 配置发现（find-postcss-config.ts）等构建细节。

文档明确提醒：绝对导入（absolute imports）无法在 story/测试中被 mock，需要 mock 时建议使用 subpath imports（package.json 的 imports 字段）方案。

安装后的常见运行问题与排查

结合 Next.js (Vite) 文档的 FAQ，安装并配置后最常遇到三类问题，可提前对照：

页面级数据请求导致构建崩溃：app 目录下的服务端组件若在 story 中被直接导入，其中只在 Node 环境运行的模块导入会让 Storybook 的 Vite 构建崩溃。推荐做法是把纯组件抽取到单独文件供 story 导入；或在 viteFinal 中配置 Vite 的 optimizeDeps.exclude 处理这些模块。
静态图片导入语义变化：切换到本框架后，图片导入不再返回原始路径字符串，而是返回一个对象（“Next.js 风格”）。应把图片导入当作 next/image 在普通开发中的用法来处理。
next/font/google 拉取失败导致流水线挂掉：构建时从 Google 拉字体可能失败。Next.js 支持通过环境变量 NEXT_FONT_GOOGLE_MOCKED_RESPONSES 指向一个 JS 模块来 mock 字体响应，CI 中配置该环境变量后，把字体 CSS 以“URL 为 key”的形式导出即可（示例见文档中的 mocked-google-fonts.js）。

小结

@storybook/nextjs-vite 的安装只有三条命令之隔（npm / pnpm / yarn），但它背后是一整套 Next.js 运行时适配：Vite 构建插件、路由与导航 mock、next/head、styled-jsx、图片导入等能力都随框架包一起提供，安装后只需把 framework 切换为 @storybook/nextjs-vite 即可获得对 next/image、next/font、绝对导入、PostCSS/Tailwind 等的开箱即用支持。关键约束是 Next.js ≥ 14.1、Vite ≥ 5 的宿主版本要求（以 package.json 中的 peerDependencies 为准），以及存量 Webpack 自定义配置需要迁移到 viteFinal 的工作量——这两点决定了它是直接安装还是先做版本升级。

storybook

Storybook is the industry standard workshop for building, documenting, and testing UI components in isolation

项目地址：https://gitcode.com/GitHub_Trending/st/storybook

登录后查看全文