Storybook 常见问题解答与技术指南

Storybook 常见问题解答与技术指南

storybook 项目地址: https://gitcode.com/gh_mirrors/sto/storybook

作为前端开发领域广受欢迎的UI组件开发工具，Storybook 在项目实践中经常会遇到各种技术问题。本文将针对开发者最常遇到的典型问题，提供专业的技术解决方案和最佳实践指南。

Angular 项目常见问题

找不到 angular.json 文件错误

当在 Angular 项目中初始化 Storybook 时，系统可能会提示"Error: No angular.json file found"。这是因为：

1. Storybook 支持单项目和多项目 Angular 工作区
2. 初始化命令必须在包含 angular.json 文件的根目录下执行

解决方案：

npx storybook@latest init

执行位置很关键 - 必须在工作区根目录运行此命令。初始化过程会：

• 创建 .storybook 文件夹
• 修改 angular.json 文件
• 为选定项目添加 Storybook 配置

禁用 Angular Ivy 编译器

在某些情况下，开发者可能需要禁用 Angular Ivy 编译器：

// .storybook/main.js
export default {
  framework: {
    name: '@storybook/angular',
    options: {
      enableIvy: false
    }
  }
}

注意：未来 Angular 版本将不再支持 View Engine，建议开发者尽快迁移到 Ivy。

禁用 ngcc 编译器

如需禁用 ngcc 编译器：

export default {
  framework: {
    name: '@storybook/angular',
    options: {
      enableNgcc: false
    }
  }
}

测试覆盖率配置

Create React App 项目中排除 stories 文件

在 CRA 项目中配置测试覆盖率时，需要排除 stories 文件：

npm test -- --coverage --collectCoverageFrom='["src/**/*.{js,jsx}","!src/**/stories/*"]'

Yarn 用户需要相应调整命令格式。

Webpack 配置共享

与 Next.js 共享 Webpack 配置

可通过创建共享配置文件实现：

// .storybook/main.js
export default {
  webpackFinal: async (baseConfig) => {
    const nextConfig = require('/path/to/next.config.js');
    return { ...baseConfig, ...nextConfig };
  }
}

模块解析问题

Yarn PnP 或 monorepo 环境问题

在这些特殊环境下，可能会遇到模块解析错误。解决方案：

// .storybook/main.js
export default {
  framework: { 
    name: '@storybook/react-webpack5',
    options: { fsCache: true }
  }
}

React 新特性支持

React 18+ 新 Root API

React 18+ 会自动使用新的 Root API。如需回退到旧版 API：

export default {
  framework: {
    name: '@storybook/react-webpack5',
    options: {
      legacyRootApi: true
    }
  }
}

常见错误排查

Addons 频道不可用

当 addon 尝试访问不存在的 channel 时：

1. 在非浏览器环境(如 Jest)中测试时，需要 mock channel：

import { addons, mockChannel } from '@storybook/preview-api';
addons.setChannel(mockChannel());

2. React Native 环境有特殊处理方式

Controls 面板不显示

确保已正确安装并配置 @storybook/addon-controls：

// .storybook/main.js
export default {
  addons: ['@storybook/addon-controls']
}

高级配置技巧

无本地 stories 的 Storybook 配置

即使使用 Storybook 组合功能，仍需至少一个本地 stories 文件。解决方案是添加一个介绍性文档：

{/* Introduction.mdx */}
# 欢迎使用

这里是项目介绍内容

然后在配置中引用：

// .storybook/main.js
export default {
  stories: ['../Introduction.mdx'],
  refs: {
    project1: { title: '项目一', url: '...' }
  }
}

版本兼容性

社区插件兼容性

注意：Storybook 6.0+ 的某些社区插件可能需要更新才能正常工作。建议：

1. 检查插件是否支持最新版
2. 关注官方兼容性列表更新

历史版本文档

如需查阅旧版文档：

• 5.3 和 5.0 是重要里程碑版本
• 更早版本需查看特定发布分支

通过本文的技术解析和解决方案，开发者可以更高效地解决 Storybook 使用过程中的各类问题，提升开发体验和效率。

storybook 项目地址: https://gitcode.com/gh_mirrors/sto/storybook