企业官网建设流程全解析

Storybook 项目中安装并启用 ESLint 与 eslint-plugin-storybook 的完整指南

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

本指南讲解如何在 Storybook 项目中从零安装 ESLint，并接入 Storybook 官方维护的eslint-plugin-storybook，让 stories 与.storybook配置始终符合 Storybook 与前端工程最佳实践。你将掌握 npm、pnpm、yarn 三种包管理器下的安装命令、.eslintrc（legacy）与eslint.config.js（flat config）两种配置形态，以及规则作用范围、覆盖与禁用方法。

ESLint 在 Storybook 工作流中的角色

Storybook 提供了独立的 code/lib/eslint-plugin 包（即eslint-plugin-storybook），用于在编写 stories 与组件时对齐最新的 Storybook 与前端开发最佳实践。包内声明为"eslintplugin"、peerDependencies: { "eslint": ">=8" }，并由 Storybook 主仓库统一维护。ESLint 本身则负责提供通用的 JavaScript/TypeScript 静态检查能力，是运行该插件的前提。

第一步：安装 ESLint

安装 ESLint 是整个流程的基础步骤，务必作为开发依赖（devDependencies）安装，因为它只服务于本地代码检查，不应进入生产运行时。

npm 用户执行：

npm install --save-dev eslint

pnpm 用户执行：

pnpm add --save-dev eslint

yarn 用户执行：

yarn add --dev eslint

安装完成后，可通过npx eslint --version验证版本。安装的 ESLint 大版本会影响后续插件版本的选择，请留意下文“ESLint 兼容性”小节。

第二步：安装 eslint-plugin-storybook

ESLint 就绪后，继续安装 Storybook 官方插件，同样作为开发依赖：

npm install --save-dev eslint-plugin-storybook

pnpm add --save-dev eslint-plugin-storybook

yarn add --dev eslint-plugin-storybook

一个值得注意的工程细节：该插件在package.json的files中打包了自身所需依赖，插件自身也“捆绑了所需的 CSF 辅助工具”，因此在共享 monorepo 的 ESLint preset 等场景中，无需为了加载该插件而单独安装 storybook 主包（见 插件 README）。

第三步：最小化接入配置

基于.eslintrc（ESLint v9 之前）

在.eslintrc配置文件的extends中加入plugin:storybook/recommended。由于 ESLint 的命名约定，此处可以省略eslint-plugin-前缀：

{ // extend plugin:storybook/<configuration>, 例如: "extends": ["plugin:storybook/recommended"] }

最后，在.eslintignore文件中追加一行：

!.storybook

这一行用于取消对.storybook目录的忽略，使插件也能 lint 目录内的配置文件（如main.js|ts）。其实际收益是：一旦在main.js|ts中拼错 addon 名称，检查即可立刻报错，保证配置始终正确。

提示：ESLint 默认会忽略node_modules与“以点开头的目录”。.eslintignore中的!.storybook正是利用忽略规则的取反语义，单独将 Storybook 配置目录重新纳入检查范围。

基于 flat config（ESLint v9 及 v8.57.0+）

若项目使用 flat config 风格，则在eslint.config.js中加入全局忽略取反：

import { defineConfig, globalIgnores } from 'eslint/config'; export default defineConfig([ globalIgnores(['!.storybook'], 'Include Storybook Directory'), // ... ]);

启用并扩展 recommended 规则集

与.eslintrc的extends不同，flat config 需要显式展开预设配置对象，再将通用的其他规则集拼接进来：

import storybook from 'eslint-plugin-storybook'; // 若使用较旧版本 ESLint，请把 eslint/config 替换为 @eslint/config-helpers import { defineConfig } from 'eslint/config'; export default defineConfig([ ...storybook.configs['flat/recommended'], // 在此追加 js.configs.recommended 等通用规则集 ]);

如果项目借助typescript-eslint等工具的辅助函数组织配置，则插件配置需要作为整体传入而不是解构：

import storybook from 'eslint-plugin-storybook'; import somePlugin from 'some-plugin'; import tseslint from 'typescript-eslint'; export default tseslint.config( somePlugin, storybook.configs['flat/recommended'], // 注意：此处不解构 );

ESLint 与插件版本兼容矩阵

插件对 ESLint 版本有对应要求，选择插件版本时按下表匹配：

插件源码中的peerDependencies声明eslint: ">=8"，而表格进一步给出了按大版本细分的历史兼容线。安装时建议让包管理器解析出与当前 ESLint 匹配的插件版本。

规则自动作用范围

启用后无需任何手动配置，插件只会作用于符合*.stories.*（推荐）或*.story.*命名约定的文件。这一点可从源码得到印证：在 code/lib/eslint-plugin/src/configs/recommended.ts 及 flat 系列配置（如 flat/recommended.ts）中，均将检查范围限定为：

**/*.stories.@(ts|tsx|js|jsx|mjs|cjs) **/*.story.@(ts|tsx|js|jsx|mjs|cjs)

因此业务代码文件不会被这些 Storybook 专属规则打扰。需要提醒的是：该插件不支持 MDX 文件，.stories.mdx不在检查范围内。

局部覆盖与禁用规则

stories 专属规则不应施加到所有文件，因此建议通过overrides（legacy）或独立 flat 配置片段，将规则调整限定在 story 文件内。

.eslintrc形态

{ "overrides": [ { // 👇 该 patterns 应与 .storybook/main.js|ts 中的 stories 属性保持一致 "files": ["**/*.stories.@(ts|tsx|js|jsx|mjs|cjs)"], "rules": { // 👇 开启某条规则 "storybook/csf-component": "error", // 👇 关闭某条规则 "storybook/default-exports": "off", } } ] }

flat config 形态

import storybook from 'eslint-plugin-storybook'; import { defineConfig } from 'eslint/config'; export default defineConfig([ ...storybook.configs['flat/recommended'], { // 👇 同样匹配 .storybook/main.js|ts 中的 stories 属性 files: ['**/*.stories.@(ts|tsx|js|jsx|mjs|cjs)'], rules: { 'storybook/csf-component': 'error', 'storybook/default-exports': 'off', }, }, ]);

内置规则速览

插件当前提供四套可继承的预设：csf、csf-strict、addon-interactions、recommended（flat 前缀的flat/xxx变体亦存在）。rules 源码位于 code/lib/eslint-plugin/src/rules，其中核心规则包括：

其中no-uninstalled-addons规则会被施加到.storybook/main.*文件，这正是上文.eslintignore取反配置让插件 lint 配置目录的直接价值。插件目录还内置了对应规则的单测（见 src/test-utils.ts），例如默认以MyComponent.stories.js作为测试用文件名，验证规则在真实命名下的行为。

验证与后续动作

完成上述安装与配置后，在项目根目录运行 ESLint 即可看到对 stories 文件的检查结果：

npx eslint "**/*.stories.{ts,tsx,js,jsx}"

若需在 CI 中强制执行，可配合 lint 脚本（如"lint": "eslint . --ext .js,.jsx,.ts,.tsx"）纳入流水线。欲进一步了解规则细节与贡献方式，可继续阅读 code/lib/eslint-plugin/README.md 与 code/lib/eslint-plugin/CONTRIBUTING.md。

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