如何在 Next.js 项目中用 nextjs-vite 框架安装 Storybook 并跑通开发模式-创锋一号

如何在 Next.js 项目中用 nextjs-vite 框架安装 Storybook 并跑通开发模式

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

你有一个已经跑起来的 Next.js 应用，现在希望用 Storybook 在隔离环境中开发、预览和测试 UI 组件。官方推荐的 Next.js 框架是nextjs-vite（对应包@storybook/nextjs-vite），它用 Vite 作为构建器，相比 Webpack 版@storybook/nextjs构建更快，且完整支持 Vitest 测试等测试功能。这篇文章覆盖从版本要求、安装到启动开发服务器并确认运行结果的完整路径。

版本要求

按 Next.js (Vite) 框架文档，使用该框架的硬性要求是：

Next.js ≥ 15
Vite ≥ 5

安装总览文档还列出了运行 Storybook CLI 的环境要求：Node.js 20+、npm 10+、pnpm 9+、Yarn 4+。如果你的 Next.js 项目尚未使用 Vite，需要先确认项目里已安装 Vite 5 及以上版本。

选择框架：nextjs-vite 还是 nextjs

在动手之前先明确一点，这决定安装命令如何走：

nextjs-vite是官方推荐选项，构建更快、HMR 更快，且无需 Babel 或复杂的 Webpack 配置；
如果你的项目已有自定义 Webpack（webpackFinal）或 Babel 配置，且你不想把它们迁移到 Vite，应选 Webpack 版的nextjs。

Storybook CLI 在安装时会检查项目依赖并自动检测项目类型，除非项目里存在自定义 Webpack 或 Babel 配置，否则默认安装nextjs-vite框架；存在自定义配置时，CLI 会停下来询问你选择哪个框架。

执行安装

在 Next.js 项目的根目录运行：

npm create storybook@latest

其他包管理器的等价命令：

pnpm create storybook@latest

yarn create storybook

安装过程会依次弹出交互式提示，按实际情况选择即可：

New to Storybook?选 "Yes" 会进入一个交互式向导并生成示例 story 供学习；有经验的话可以跳过，得到一个最小化安装。
What configuration should we install?两个选项：
- Recommended：包含组件开发、文档、测试、无障碍检查功能；
- Minimal：只装组件开发必需的部分。
也可以跳过交互，直接用--features参数手动指定功能，例如：
```
npm create storybook@latest --features docs test a11y
```

安装完成后，该命令会对本地项目做以下变更：

安装所需依赖；
配置好运行和构建 Storybook 的脚本；
添加默认 Storybook 配置（.storybook目录）；
加入一些样板 story；
开启匿名遥测（可查阅遥测文档了解如何退出）。

启动开发模式并验证结果

安装成功后，在同一个项目根目录运行：

npm run storybook

（pnpm 用pnpm run storybook，Yarn 用yarn storybook。）

这条命令会启动内置开发服务器：终端输出访问地址，并自动在新浏览器标签页打开 Storybook 的欢迎界面。开发模式跑通的判断依据是能看到类似文档中的欢迎界面：

界面上的关键内容：

一组指向配置和自定义选项的链接；
若干示例 story（对应安装时生成的样板 story）；
如果你跳过了 onboarding 向导且示例 story 还在，可以在 Storybook URL 后追加?path=/onboarding重新打开向导。

看到界面并能在示例 story 中正常切换，说明nextjs-vite框架的开发模式已经跑通。接下来可以按 writing stories 文档开始写组件 story，或参考 writing docs、running tests 继续深入。

可选分支：手动安装 nextjs-vite 框架

如果不走交互式 CLI，也可以手动安装（框架文档的迁移章节中同样给出这一路径）：

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

然后在.storybook/main.js或.storybook/main.ts中把framework属性指向该包，例如 TS 配置：

import type { StorybookConfig } from '@storybook/nextjs-vite'; const config: StorybookConfig = { framework: '@storybook/nextjs-vite', }; export default config;

这条路径适合从其他框架（如@storybook/nextjs）迁移或已有 Storybook 配置的项目。注意迁移自 Webpack 配置时，webpackFinal中的自定义逻辑需要改写到viteFinal，直接.md导入还需要加 Vite 的?raw后缀——这些细节在框架文档的迁移小节有说明。

排查与限制

安装或启动遇到问题时，对照文档给出的处理方式：

CLI 没有检测到 Next.js 项目：用--type显式指定项目类型。允许的值中 Next.js 对应nextjs：
```
npm create storybook@latest --type nextjs
```
想强制指定包管理器：给安装命令追加--package-manager标志，例如npm create storybook@latest --package-manager=npm。
空目录初始化问题：在一个只有package.json的目录里初始化 Vite 系框架时，Yarn Modern 可能因 peer 依赖处理导致问题；解决办法是先用包管理器手动安装 Vite，再运行 Storybook 初始化命令。
avif 图片报错：如果构建时报You are importing avif images, but you don't have sharp installed，按文档在项目中安装sharp（npm install sharp/yarn add sharp/pnpm add sharp均可）。

下一步

开发模式跑通之后，生产构建用另一条脚本：

npm run build-storybook

产物输出到配置的outputDir，默认是storybook-static。

边界说明：本文只覆盖 Next.js 项目使用nextjs-vite框架的安装与开发模式；如果你决定保留 Webpack 5 方案，请改用@storybook/nextjs框架文档，两条路径的配置项（如webpackFinal与viteFinal）不通用。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析