适用于 ESLint V9 的现代化扁平化配置

开源

程

程沛权2025/3/14 00:35:02

Star on GitHub

ESLint v9.0.0 是 ESLint 的一个主要版本，它有几个重大变化，其中最大的变化是其配置文件和插件生态系统的使用，可以通过官方网站的迁移到 v9.x 文档了解如何迁移。

这里有一个关于 ESLint V9 的扁平化配置的 npm 包，内置了一些个人常用的 ESLint 配置，这也是我在 GitHub 上发布的一个开源项目。如果它对您有帮助，请给它一个 Star ！

一款现代化的扁平 ESLint 配置，适用于 ESLint V9 ，由 @chengpeiquan 精心打造。

⚡ 使用方法

使用此 ESLint 配置仅需三步：

安装依赖（参考：🚀 安装）
添加 ESLint 配置文件（参考：📂 配置文件）
在 VS Code 的 settings.json 启用自动 Lint（参考：🛠 VS Code 配置）

这个快速指南可以作为入门辅助，避免遗漏关键步骤 🚀 。

🚀 安装

使用常用的包管理器安装该包：

npm install -D eslint @bassist/eslint-config

注意： 需要 ESLint 版本 >= 9.0.0 ，以及 TypeScript 版本 >= 5.0.0。

如果使用的是 pnpm，建议在项目根目录添加 .npmrc 文件，并包含以下配置，以更顺利地处理 peer 依赖：

shamefully-hoist=true
auto-install-peers=true

如果仍在使用 ESLint v8，请参考旧版（已不再维护）包：@bassist/eslint。

📂 配置文件

在项目根目录创建 eslint.config.js 文件：

// eslint.config.js
import { imports, typescript } from '@bassist/eslint-config'

// 导出一个包含多个配置对象的数组
export default [...imports, ...typescript]

然后在 package.json 中添加 "type": "module" ：

{
  "type": "module",
  "scripts": {
    "lint": "eslint src",
    "lint:inspector": "npx @eslint/config-inspector"
  }
}

运行 npm run lint 以检查代码，或运行 npm run lint:inspector 在 http://localhost:7777 查看可视化的 ESLint 配置。

对于 TypeScript 配置文件（例如 eslint.config.ts ），需要额外的设置。

# 为 Node.js 提供运行时 TypeScript 和 ESM 支持
npm install -D jiti

✅ 类型安全的配置

为了增强类型安全性，可以使用 defineFlatConfig:

// @ts-check
import { defineFlatConfig, imports, vue } from '@bassist/eslint-config'

export default defineFlatConfig([
  ...imports,
  ...vue,
  // 添加更多自定义配置
  {
    // 为每个配置提供名称，以便在运行 `npm run lint:inspector` 时，
    // 可以在可视化工具中清晰展示
    name: 'my-custom-rule/vue',
    rules: {
      // 例如：默认情况下，该规则是 `off`
      'vue/component-tags-order': 'error',
    },
    ignores: ['examples'],
  },
])

🛠 VS Code 配置

在 VS Code 工作区的 settings.json 添加以下配置，以启用自动 Lint 修复：

{
  "editor.formatOnSave": true,
  "eslint.useFlatConfig": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "always",
    "source.fixAll.prettier": "always"
  }
}

📘 API 参考

defineFlatConfig

定义 ESLint 配置，可选支持 Prettier 和 Tailwind CSS。

API 类型声明：

/**
 * 定义 ESLint 配置，可选支持 Prettier 集成。
 *
 * @param configs 基础 ESLint 配置数组。
 * @param options - 配置选项。
 *
 * @returns 最终的 ESLint 配置数组。
 */
declare const defineFlatConfig: (
  configs: FlatESLintConfig[],
  options?: DefineFlatConfigOptions,
) => FlatESLintConfig[]

选项类型声明：

interface DefineFlatConfigOptions {
  /**
   * 指定用于加载 `.prettierrc` 配置的工作目录。
   *
   * 配置文件应为 JSON 格式。
   *
   * @default process.cwd()
   */
  cwd?: string

  /**
   * 如果 `prettierEnabled` 设为 `false`，则所有与 Prettier 相关的规则和配置都将被忽略，
   * 即使提供了 `prettierRules` 也不会生效。
   *
   * @default true
   */
  prettierEnabled?: boolean

  /**
   * 默认情况下，会从当前工作目录读取 `.prettierrc`，并且 `.prettierrc` 文件必须是 JSON 格式。
   *
   * 如果配置文件不是 JSON 格式，或者使用了不同的文件名，可以将其转换为 JSON 规则后传入。
   *
   * 读取自定义配置后，会与默认的 ESLint 规则合并。
   *
   * @see https://prettier.io/docs/configuration.html
   */
  prettierRules?: PartialPrettierExtendedOptions

  /**
   * Tailwind CSS 规则默认启用。如果它们影响了项目，可以通过该选项禁用。
   *
   * @default true
   */
  tailwindcssEnabled?: boolean

  /**
   * 如果需要覆盖 Tailwind CSS 配置，可以传入相应的选项。
   *
   * 如果想要合并配置，可以导入 `defaultTailwindcssSettings`，手动合并后再传入。
   *
   * 如果传入空对象 `{}`，则会使用默认设置。
   */
  tailwindcssSettings?: TailwindcssSettings
}

createGetConfigNameFactory

createGetConfigNameFactory 是一个灵活的工具函数，用于生成 ESLint 配置命名工具。它可以快速拼接配置名称，确保命名空间一致，并便于组织和管理复杂的规则集。

API 类型声明：

/**
 * 一个灵活的工具函数，用于生成 ESLint 配置命名工具。
 * 它可以快速拼接配置名称，确保命名空间一致，并便于组织和管理复杂的规则集。
 *
 * @param prefix - 表示配置名称前缀的字符串。
 * @returns 一个函数，该函数会将提供的名称片段与指定的前缀拼接在一起。
 */
declare const createGetConfigNameFactory: (
  prefix: string,
) => (...names: string[]) => string

使用示例：

import {
  createGetConfigNameFactory,
  defineFlatConfig,
} from '@bassist/eslint-config'

const getConfigName = createGetConfigNameFactory('my-prefix')

export default defineFlatConfig([
  {
    name: getConfigName('ignore'), // --> `my-prefix/ignore`
    ignores: ['**/dist/**', '**/.build/**', '**/CHANGELOG.md'],
  },
])

为什么要使用它？

一致性：强制执行清晰统一的配置命名模式。
灵活性：允许为不同项目或范围自定义前缀。
简化管理：便于组织和浏览大型 ESLint 配置。

这个工具在构建可复用的 ESLint 配置或维护复杂项目的规则集时尤其有用。

📦 导出的配置

这些是一些常用的配置，如果有额外需求，欢迎提交 PR！

语言支持

框架支持

格式化工具

格式化规则默认启用，不会单独导出。如需自定义配置，请通过 defineFlatConfig API 的 options 传入。

Prettier : 默认会读取 .prettierrc 和 .prettierignore 的内容，并添加到 ESLint 规则中。
Tailwind CSS : 默认会将 tailwind.config.js 作为 Tailwind CSS 配置文件传入。

程沛权