文章· 2024年4月10日

Nuxt ESLint 集成焕新

我们改进了 ESLint 集成，以支持带有 Flat Config 的 ESLint v9，以及一个具有更多功能的新模块。

Anthony Fu

@antfu

背景

ESLintESLint 已成为当今 Web 开发中不可或缺的工具。它能帮助您捕获错误并在项目中强制执行一致的编码风格。在 Nuxt，我们尽力为 ESLint 提供开箱即用的体验，使其易于使用、配置并遵循我们推荐的最佳实践。

自那以后，Nuxt 和 ESLint 都发展了很多。在过去，我们最终为 Nuxt 中的 ESLint 准备了几个不同的包和集成，并且并非总是清楚哪个用于什么目的。我们收到了社区的很多反馈。

为了改善这种情况并使其面向未来，我们最近更新了 ESLint 集成，以支持ESLint v9及其Flat Config。它为定制您的 ESLint 设置开辟了更多功能，提供了更直接、更统一的体验。

Nuxt ESLint Monorepo

我们将分散在不同存储库中的 ESLint 相关包整合到一个单一的 Monorepo 中nuxt/eslint，并为此创建了一个专门的新文档网站eslint.nuxt.com.

为了帮助理解每个包之间的差异以及何时使用哪个包，我们还提供了一个常见问题页面，其中比较了它们并解释了它们的作用域。

这个 Monorepo 现在包括：

@nuxt/eslint - 适用于 Nuxt 3 的全新一体化 ESLint 模块，支持项目感知型 ESLint Flat Config 及更多功能。
@nuxt/eslint-config - 适用于 Nuxt 3 的非强制性但可定制的共享 ESLint 配置。同时支持Flat Config 格式等等和传统格式.
@nuxt/eslint-plugin - 适用于 Nuxt 3 的 ESLint 插件，提供 Nuxt 特定的规则和配置。
两个用于 Nuxt 2 的维护模式包。

ESLint Flat Config

在深入了解新的 Nuxt 集成之前，让我向您介绍ESLint Flat Config.

的概念。Flat Config 是在 ESLint v8.21.0 中作为实验性功能引入的配置格式，并在ESLint v9.

一个快速区分的参考：

Flat Config: eslint.config.js eslint.config.mjs 等。
Legacy Config: .eslintrc .eslintrc.json .eslintrc.js 等。

为什么选择 Flat Config？

ESLint 的这篇博客文章详细解释了 Flat Config 系统的动机。简而言之，传统的 eslintrc 格式是在 JavaScript 的早期设计的，当时 ES 模块和现代 JavaScript 功能尚未标准化。其中涉及许多隐式约定，并且 extends 功能使得最终的配置结果难以理解和预测。这也使得共享配置难以维护和调试。

.eslintrc

{
  "extends": [
    // Solve from `import("@nuxtjs/eslint-config").then(mod => mod.default)`
    "@nuxtjs",
    // Solve from `import("eslint-config-vue").then(mod => mod.default.configs["vue3-recommended"])`
    "plugin:vue/vue3-recommended",
  ],
  "rules": {
    // ...
  }
}

新的 Flat Config 将插件和配置的解析从 ESLint 的内部约定转移到原生的 ES 模块解析。这反过来使其更加明确和透明，甚至允许您从其他模块导入它。由于 Flat Config 只是一个 JavaScript 模块，它也为更多的自定义打开了大门。

Flat Config 的 Nuxt 预设

在最新的@nuxt/eslint-config 包中，我们利用了其灵活性，提供了一个工厂函数，允许您以更高级别的方式轻松自定义配置预设。以下是您如何使用它的示例：

eslint.config.js

import { createConfigForNuxt } from '@nuxt/eslint-config/flat'

export default createConfigForNuxt()

@nuxt/eslint-config 从一个非强制性的基础配置开始，这意味着我们只包含了 TypeScript、Vue 和 Nuxt 的最佳实践规则，而将代码风格、格式化等其余部分留给您决定。您也可以同时运行Prettier进行格式化，使用默认设置。

该配置还允许您根据需要选择启用更多有主见的功能。例如，如果您希望 ESLint 也负责格式化，您可以通过将 features.stylistic 传递给工厂函数来启用它（由ESLint Stylistic):

eslint.config.js

import { createConfigForNuxt } from '@nuxt/eslint-config/flat'

export default createConfigForNuxt({
  features: {
    stylistic: true
  }
})

或者通过选项对象调整您的偏好（在此处了解更多选项):

eslint.config.js

import { createConfigForNuxt } from '@nuxt/eslint-config/flat'

export default createConfigForNuxt({
  features: {
    stylistic: {
      semi: false,
      indent: 2, // 4 or 'tab'
      quotes: 'single',
      // ... and more
    }
  }
})

）。如果您正在编写 Nuxt 模块，您可以启用 features.tooling 来启用 Nuxt 模块开发的规则。

eslint.config.js

import { createConfigForNuxt } from '@nuxt/eslint-config/flat'

export default createConfigForNuxt({
  features: {
    tooling: true
  }
})

等等。Flat Config 中的工厂函数允许预设覆盖底层 ESLint 配置的复杂性，并为最终用户提供高级且用户友好的抽象，以便进行自定义。所有这些都无需用户担心内部细节。

虽然这种方法通过最小化配置为您提供类似 Prettier 的体验（因为它由 ESLint 提供支持），但您仍然可以根据需要完全灵活地自定义和覆盖细粒度规则和插件。

我们还利用eslint-flat-config-utils中的FlatConfigComposer工具，使覆盖和扩展 Flat Config 变得更加容易。@nuxt/eslint-config/flat 中的工厂函数返回一个 FlatConfigComposer 实例。

eslint.config.js

import { createConfigForNuxt } from '@nuxt/eslint-config/flat'

export default createConfigForNuxt({
  // ...options for Nuxt integration
})
  .append(
    // ...append other flat config items
  )
  .prepend(
    // ...prepend other flat config items before the base config
  )
  // override a specific config item based on their name
  .override(
    'nuxt/typescript', // specify the name of the target config, or index
    {
      rules: {
        // ...override the rules
        '@typescript-eslint/no-unsafe-assignment': 'off'
      }
    }
  )
  // an so on, operations are chainable

通过这种方法，我们兼顾了两种优势：易于使用的简洁高级抽象，以及用于自定义和微调的强大功能。

Nuxt ESLint 模块

更进一步，我们为 Nuxt 3 制作了新的、一体化的@nuxt/eslint 模块。它利用 Nuxt 的上下文为您的项目生成项目感知和类型安全的 ESLint 配置。

我们知道 Vue 的样式指南建议对组件使用多词名称，以避免与现有和未来的 HTML 元素冲突。因此，在eslint-plugin-vue中，我们默认启用了vue/multi-word-component-names规则。这是一个很好的实践，但我们知道在 Nuxt 项目中，并非所有 .vue 文件都注册为组件。诸如 app.vue、pages/index.vue、layouts/default.vue 等文件不能作为其他 Vue 文件中的组件使用，因此该规则与它们无关。

通常，我们可以为这些文件关闭规则，例如

eslint.config.js

export default [
  {
    files: ['*.vue'],
    rules: {
      'vue/multi-word-component-names': 'error'
    }
  },
  {
    files: ['app.vue', 'error.vue', 'pages/**/*.vue', 'layouts/**/*.vue'],
    rules: {
      // disable the rule for these files
      'vue/multi-word-component-names': 'off'
    }
  }
]

它应该适用于大多数情况。然而，我们知道在 Nuxt 中，您可以自定义每个目录的路径和层级允许您为每个目录设置多个来源。这意味着 Linter 规则的准确性会降低，并且可能导致用户需要额外的工作才能手动保持它们一致。

同样，我们希望只对 pages 和 layouts 等启用vue/no-multiple-template-root。随着情况越来越多，要求用户手动维护规则变得不切实际。

这就是 @nuxt/eslint 的魔力所在！它利用 Nuxt 的上下文来生成特定于您的项目结构的配置和规则。这与 Nuxt 提供的.nuxt/tsconfig.json非常相似，您现在也有了项目感知的 .nuxt/eslint.config.mjs 可以扩展。

要使用它，您可以将模块添加到您的 Nuxt 项目中

终端

npx nuxi module add eslint

配置检查器 DevTools 集成

在迁移和研究新的 Flat Config 期间，我萌生了制作一个交互式 UI 检查器来检查 Flat Config 的想法，以使配置更加透明和易于理解。当您安装了 @nuxt/eslint 模块时，我们已将其集成到Nuxt DevTools中，以便您可以随时轻松访问它。

Screenshot of ESLint Config Inspector running as a tab in Nuxt DevTools

该检查器允许您查看最终解析的配置、已启用的规则和插件，并进行快速匹配，以查看规则和配置如何应用于特定文件。它非常适合调试和学习 ESLint 在您的项目中如何工作。

我们很高兴 ESLint 团队也认为它很有用，并有兴趣将其推广到更广泛的 ESLint 社区。我们后来加入了这项工作，并将其制作成官方 ESLint 配置检查器（顺便说一下，它是用 Nuxt 构建的）。您可以阅读此公告文章以获取更多详细信息。

规则的类型生成

配置 ESLint 的主要痛点之一是规则和配置的类型信息泄露。很难知道特定规则有哪些可用选项，您需要为每个规则查阅文档才能找出答案。

再次感谢新的 Flat Config 带来了如此多的动态可能性。我们发现了一个新工具，eslint-typegen，我们可以根据您实际使用的插件从每个规则的规则配置模式生成相应的类型。这意味着它是一个适用于任何 ESLint 插件的通用解决方案，并且类型始终准确且最新。

在 @nuxt/eslint 模块中，此功能是开箱即用的，因此您将立即获得这种出色的体验。

Screenshot of VS Code that showcases the type check and autocomplete with ESLint rules config

开发服务器检查器

通过新模块，我们借此机会将@nuxtjs/eslint-module以及 ESLint 的开发服务器检查器合并到新的 @nuxt/eslint 模块中，作为一项可选功能。

您可能大部分时间不需要此功能，因为您的编辑器集成应该已经在编辑器中提供了 ESLint 诊断。但是，对于某些使用不同编辑器并希望确保 ESLint 始终运行的团队来说，能够在开发服务器中运行 ESLint 在某些情况下可能会有所帮助。

要启用它，您可以在模块选项中将 checker 选项设置为 true。

nuxt.config.ts

export default defineNuxtConfig({
  modules: [
    '@nuxt/eslint'
  ],
  eslint: {
    checker: true // <---
  }
})

每当您遇到一些 ESLint 错误时，您会在控制台和浏览器中看到警告。要了解有关此功能的更多信息，您可以查看文档.

模块钩子

由于我们现在在 Nuxt 模块中拥有代码生成功能和项目感知配置，我们实际上可以用它做更多有趣的事情。其中之一是我们可以允许模块也对 ESLint 配置做出贡献。想象一下，将来，当您安装一个像 @nuxtjs/i18n 这样的 Nuxt 模块时，它可以自动为与 i18n 相关的文件启用特定的 ESLint 规则；或者当您安装像 @pinia/nuxt 这样的模块时，它可以安装 Pinia ESLint 插件以强制执行 Pinia 的最佳实践等。

作为一项实验，我们制作了一个模块nuxt-eslint-auto-explicit-import，它可以利用预配置的 ESLint 预设，为 Nuxt 项目中注册的自动导入功能自动插入显式导入。这样，您在使用 API 时仍然可以获得与自动导入相同的良好开发体验，同时在代码库中拥有自动插入的显式导入。

这仍处于早期阶段，我们仍在探索可能性和最佳实践。但我们对它所带来的潜力感到非常兴奋。我们将与社区合作，看看如何充分利用它。如果您有任何想法或反馈，请随时与我们分享！

生态系统

在 Nuxt，我们一如既往地非常关心生态系统和社区。在我们探索采用新的 Flat Config 并改进开发体验的过程中，我们制作了一些工具来实现这一目标。所有这些都是通用目的的，可以在 Nuxt 之外使用：

@eslint/config-inspector- 官方 ESLint Config Inspector，为您的配置提供交互式 UI。
eslint-typegen- 根据您实际使用的插件生成 ESLint 规则的 TypeScript 类型。
FlatConfigComposer- 用于管理和组合 ESLint Flat Config 的实用工具。

我们致力于支持更广泛的社区，并与开发人员合作改进这些工具并扩展其可能性。我们很高兴看到这些工具能为 ESLint 生态系统带来益处，并为整体开发体验做出贡献。

未来

Flat Config 格式仍然相当新，ESLint v9 也才发布几周。插件和社区正在逐渐跟上新格式。它仍处于探索和实验阶段。

展望未来，我们渴望看到 ESLint 生态系统将如何继续发展，以及我们如何利用新功能和可能性来进一步提升 Nuxt 的开发体验。我们致力于为 Nuxt 用户提供无缝且强大的开发环境，并将继续探索新想法并与社区合作以实现这一目标。

← 返回博客

Nuxt 2 生命周期结束 (EOL)

Nuxt 2 将于 2024 年 6 月 30 日结束生命周期 (EOL)。我们与 HeroDevs 合作提供永不停止的支持 (NES)。

Shiki v1.0 的演进

Shiki v1.0 带来了许多改进和功能——看看 Nuxt 如何推动 Shiki 的演进！

Nuxt ESLint 集成焕新

TL;DR

背景

Nuxt ESLint Monorepo

ESLint Flat Config

为什么选择 Flat Config？

Flat Config 的 Nuxt 预设

Nuxt ESLint 模块

项目感知规则

配置检查器 DevTools 集成

规则的类型生成

开发服务器检查器

模块钩子

生态系统

未来