Storybook 在 Next.js 项目中的完整使用指南-优快云博客

Storybook 在 Next.js 项目中的完整使用指南

【免费下载链接】storybook 项目地址: https://gitcode.com/gh_mirrors/sto/storybook

前言

Storybook 是一个强大的 UI 组件开发环境，它允许开发者独立构建、测试和文档化组件。对于 Next.js 项目，Storybook 提供了专门的框架支持，使得在 Next.js 环境中开发组件变得更加高效和便捷。

核心功能支持

Storybook for Next.js 提供了对 Next.js 核心功能的完整支持：

路由系统：自动模拟 Next.js 的路由功能
图片优化：支持 Next.js 的 Image 组件
绝对路径导入：与 Next.js 的路径别名兼容
样式处理：支持 CSS/Sass/Scss 模块
构建配置：自动继承 Next.js 的 Webpack 和 Babel 配置

环境要求

Next.js ≥ 13.5 版本
Storybook ≥ 7.0 版本

安装与配置

全新项目初始化

对于尚未集成 Storybook 的 Next.js 项目，执行以下命令：

npx storybook init

该命令会自动检测项目类型并配置适当的 Storybook 环境。

已有项目升级

对于已使用 Storybook 的项目，首先升级到最新版本：

npx storybook upgrade

然后安装 Next.js 框架支持：

npm install @storybook/nextjs --save-dev

更新配置文件 .storybook/main.js|ts：

module.exports = {
  framework: '@storybook/nextjs',
  // 其他配置...
}

Next.js 核心功能集成

图片组件支持

Storybook 完全支持 Next.js 的 Image 组件，包括本地和远程图片：

import Image from 'next/image';

// 本地图片
import profilePic from '../public/me.png';
<Image src={profilePic} alt="Profile" />

// 远程图片
<Image src="/me.png" alt="Profile" width={500} height={500} />

字体优化

支持 next/font 的 Google 字体和本地字体：

// Google 字体
import { Inter } from 'next/font/google';
const inter = Inter({ subsets: ['latin'] });

// 本地字体
import localFont from 'next/font/local';
const myFont = localFont({ src: './fonts/my-font.woff2' });

对于本地字体，需要在 Storybook 配置中指定静态目录：

// .storybook/main.js
module.exports = {
  staticDirs: [
    {
      from: '../public/fonts',
      to: 'fonts'
    }
  ]
}

路由系统

Storybook 模拟了 Next.js 的路由功能，支持 next/router 和 next/navigation：

// pages 目录组件
import { useRouter } from 'next/router';

// app 目录组件
import { useRouter } from 'next/navigation';

可以通过参数覆盖默认路由行为：

// 在 story 文件中
export default {
  parameters: {
    nextjs: {
      router: {
        pathname: '/custom-path',
        query: { id: '123' }
      }
    }
  }
}

Head 组件支持

next/head 组件可以直接在故事中使用：

import Head from 'next/head';

function MyComponent() {
  return (
    <>
      <Head>
        <title>My Page Title</title>
      </Head>
      {/* 组件内容 */}
    </>
  );
}

样式处理

Sass/Scss 支持

Storybook 自动继承 Next.js 的 Sass 配置：

// .storybook/preview.js
import '../styles/globals.scss';

CSS 模块

CSS 模块开箱即用：

import styles from './Button.module.css';

function Button() {
  return <button className={styles.primary}>Click me</button>;
}

最佳实践

组件隔离：确保每个故事只展示一个明确的组件状态
交互测试：利用 Storybook 的交互测试功能验证组件行为
文档化：为每个组件编写清晰的文档和使用示例
视觉测试：集成视觉回归测试确保 UI 一致性
性能考虑：对于复杂组件，考虑使用加载状态故事

常见问题解决

字体加载失败

在 CI/CD 环境中，可以模拟 Google 字体请求：

// mocked-google-fonts.js
module.exports = {
  'https://fonts.googleapis.com/css...': `
    @font-face {
      font-family: 'Inter';
      font-style: normal;
      src: url(/mock-font.woff2) format('woff2');
    }
  `
};

路由行为异常

可以通过全局配置覆盖默认路由：

// .storybook/preview.js
import { getRouter } from '@storybook/nextjs/router.mock';

export const parameters = {
  nextjs: {
    router: {
      basePath: '/app'
    }
  }
};

总结

Storybook 为 Next.js 项目提供了完整的组件开发解决方案，从图片优化到路由模拟，从样式处理到字体加载，几乎覆盖了 Next.js 的所有核心功能。通过合理配置，开发者可以在隔离环境中高效构建和测试 UI 组件，显著提升开发体验和组件质量。

【免费下载链接】storybook 项目地址: https://gitcode.com/gh_mirrors/sto/storybook

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