Nuxt ESLint 集成已更新

背景

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

由于 Nuxt 和 ESLint 都已经发展了很多。从历史上看，我们最终为 Nuxt 中的 ESLint 提供了一些不同的包和集成，而且并非总是很明显应该将哪个用于什么目的。我们收到了社区的大量反馈。

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

Nuxt ESLint Monorepo

我们将分散在不同存储库中的 ESLint 相关软件包移动到一个单一的 monorepo 中：nuxt/eslint，并提供了一个专门的新文档站点：eslint.nuxt.com。

为了帮助理解每个软件包之间的差异以及应该使用哪个，我们还提供了一个 FAQ 页面，比较了它们并解释了它们的作用域。

此 monorepo 现在包含

@nuxt/eslint - 用于 Nuxt 3 的全新一体化 ESLint 模块，支持项目感知的 ESLint 扁平配置以及更多功能。
@nuxt/eslint-config - 用于 Nuxt 3 的非强制性但可自定义的共享 ESLint 配置。同时支持扁平配置格式和旧版格式。
@nuxt/eslint-plugin - 用于 Nuxt 3 的 ESLint 插件，提供 Nuxt 特定的规则和配置。
两个用于 Nuxt 2 的软件包，处于维护模式。

ESLint 扁平配置

在深入研究新的 Nuxt 集成之前，让我向您介绍 ESLint 扁平配置的概念。

扁平配置是 ESLint v8.21.0 中作为实验性引入的一种配置格式，并在 ESLint v9 中成为默认格式。

区分的快速参考

扁平配置：eslint.config.js eslint.config.mjs 等。
旧版配置：.eslintrc .eslintrc.json .eslintrc.js 等。

为什么选择扁平配置？

ESLint 的这篇博文详细解释了扁平配置系统背后的动机。简而言之，旧版 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": {
    // ...
  }
}

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

用于扁平配置的 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
  }
})

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

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

我们还制作了一个来自 eslint-flat-config-utils 的 FlatConfigComposer 实用程序，使覆盖和扩展扁平配置更加容易。@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 中，您可以自定义每个目录的路径，并且 layers 允许您为每个目录拥有多个来源。这意味着 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 集成

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

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

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

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

规则的类型生成

配置 ESLint 的主要痛点之一是规则和配置的类型信息泄漏。很难知道特定规则有哪些选项可用，并且需要您跳转到每个规则的文档才能弄清楚。

再次感谢新的扁平配置具有如此多的可能性的动态性。我们找到了一个新的工具 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，它可以为您的 Nuxt 项目中注册的自动导入使用预配置的 ESLint 预设进行自动插入。这样，您在使用 API 的自动导入时可以获得相同的良好开发者体验，但在您的代码库中仍然具有自动插入的显式导入。

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

生态系统

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

@eslint/config-inspector - 官方 ESLint 配置检查器，为您的配置提供交互式 UI。
eslint-typegen - 根据您正在使用的实际插件，为 ESLint 规则生成 TypeScript 类型。
eslint-flat-config-utils - 用于管理和组合 ESLint 扁平配置的实用程序。

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

未来

扁平配置格式仍然相当新，ESLint v9 仅在几周前发布。插件和社区正在逐步赶上新的格式。它仍处于探索和实验阶段。

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

← 返回博客

Nuxt 3.12

Nuxt 3.12 发布 - 充满改进，并为 Nuxt 4 做好准备！

Nuxt：展望未来

在过去一年中，Nuxt 发生了很多事情。Sébastien 和 Daniel 分享了他们对我们已取得成就以及未来发展方向的看法。

TL;DR（太长不看）

背景

Nuxt ESLint Monorepo

ESLint 扁平配置

为什么选择扁平配置？

用于扁平配置的 Nuxt 预设

Nuxt ESLint 模块

项目感知规则

配置检查器 DevTools 集成

规则的类型生成

开发服务器检查器

模块钩子

生态系统

未来