ESLint

Next.js 提供了开箱即用的集成 ESLint 体验。将 next lint 作为脚本添加到 package.json 中

{
  "scripts": {
    "lint": "next lint"
  }
}

然后运行 npm run lint 或 yarn lint

yarn lint

如果你的应用程序中尚未配置 ESLint，系统会引导你完成安装和配置过程。

yarn lint

你会看到类似这样的提示

? 你想如何配置 ESLint？

❯ 严格模式 (推荐)
基础模式
取消

可以选择以下三个选项之一

• **严格模式**：包含 Next.js 的基础 ESLint 配置以及更严格的 核心 Web 指标规则集。这是首次为开发者设置 ESLint 的推荐配置。

  .eslintrc.json

  {
    "extends": "next/core-web-vitals"
  }

• **基础模式**：包含 Next.js 的基础 ESLint 配置。

  .eslintrc.json

  {
    "extends": "next"
  }

• **取消**：不包含任何 ESLint 配置。仅在你计划设置自己的自定义 ESLint 配置时选择此选项。

如果选择了这两个配置选项中的任何一个，Next.js 会自动将 eslint 和 eslint-config-next 作为依赖项安装到你的应用程序中，并在项目的根目录中创建一个包含你所选配置的 .eslintrc.json 文件。

现在，你可以随时运行 next lint 来运行 ESLint 以捕获错误。设置 ESLint 后，它也会在每次构建 (next build) 期间自动运行。错误会导致构建失败，而警告则不会。

如果你不希望 ESLint 在 next build 期间运行，请参阅 忽略 ESLint 的文档。

我们建议使用合适的 集成，以便在开发过程中直接在代码编辑器中查看警告和错误。

ESLint 配置

默认配置 (eslint-config-next) 包含你在 Next.js 中获得最佳开箱即用整理体验所需的一切。如果你的应用程序中尚未配置 ESLint，我们建议使用 next lint 来设置 ESLint 以及此配置。

如果你想将 eslint-config-next 与其他 ESLint 配置一起使用，请参阅 其他配置 部分，了解如何在不造成任何冲突的情况下执行此操作。

以下 ESLint 插件的推荐规则集都用于 eslint-config-next 中

• eslint-plugin-react
• eslint-plugin-react-hooks
• eslint-plugin-next

这将优先于 next.config.js 中的配置。

ESLint 插件

Next.js 提供了一个 ESLint 插件，eslint-plugin-next，它已捆绑在基础配置中，使你能够在 Next.js 应用程序中捕获常见的问题。完整的规则集如下

在推荐配置中启用

如果您已经在应用程序中配置了 ESLint，我们建议直接从该插件扩展，而不是包含 eslint-config-next，除非满足一些条件。请参阅 推荐插件规则集 以了解更多信息。

自定义设置

rootDir

如果您在 Next.js 未安装在根目录（例如单一仓库）的项目中使用 eslint-plugin-next，您可以使用 .eslintrc 中的 settings 属性告诉 eslint-plugin-next 在哪里找到您的 Next.js 应用程序。

{
  "extends": "next",
  "settings": {
    "next": {
      "rootDir": "packages/my-app/"
    }
  }
}

rootDir 可以是路径（相对或绝对）、通配符（例如 "packages/*/"）或路径和/或通配符的数组。

整理自定义目录和文件

默认情况下，Next.js 将为 pages/、app/、components/、lib/ 和 src/ 目录中的所有文件运行 ESLint。但是，您可以使用 next.config.js 中 eslint 配置的 dirs 选项为生产版本指定要整理的目录。

module.exports = {
  eslint: {
    dirs: ['pages', 'utils'], // Only run ESLint on the 'pages' and 'utils' directories during production builds (next build)
  },
}

类似地，--dir 和 --file 标志可用于 next lint 以整理特定的目录和文件。

next lint --dir pages --dir utils --file bar.js

缓存

为了提高性能，默认情况下，ESLint 处理的文件信息会被缓存。它存储在 .next/cache 或您定义的 构建目录 中。如果您包含任何依赖于单个源文件之外内容的 ESLint 规则并且需要禁用缓存，请在 next lint 中使用 --no-cache 标志。

next lint --no-cache

禁用规则

如果您想修改或禁用支持的插件（react、react-hooks、next）提供的任何规则，您可以使用 .eslintrc 中的 rules 属性直接更改它们。

{
  "extends": "next",
  "rules": {
    "react/no-unescaped-entities": "off",
    "@next/next/no-page-custom-font": "off"
  }
}

核心网络指标

当首次运行 next lint 并选择 严格 选项时，将启用 next/core-web-vitals 规则集。

{
  "extends": "next/core-web-vitals"
}

next/core-web-vitals 将 eslint-plugin-next 更新为对一些默认情况下为警告的规则进行错误处理，如果这些规则会影响 核心网络指标。

使用 Create Next App 构建的新应用程序会自动包含 next/core-web-vitals 入口点。

TypeScript

除了 Next.js ESLint 规则之外，create-next-app --typescript 还会将 TypeScript 特定的 lint 规则（使用 next/typescript）添加到您的配置中。

{
  "extends": ["next/core-web-vitals", "next/typescript"]
}

这些规则基于 plugin:@typescript-eslint/recommended。有关更多详细信息，请参阅 typescript-eslint > Configs。

与其他工具一起使用

Prettier

ESLint 还包含代码格式化规则，这可能与您现有的 Prettier 设置冲突。我们建议在您的 ESLint 配置中包含 eslint-config-prettier 以使 ESLint 和 Prettier 协同工作。

首先，安装依赖项。

npm install --save-dev eslint-config-prettier
 
yarn add --dev eslint-config-prettier
 
pnpm add --save-dev eslint-config-prettier
 
bun add --dev eslint-config-prettier

然后，将 prettier 添加到您现有的 ESLint 配置中。

{
  "extends": ["next", "prettier"]
}

lint-staged

如果您想将 next lint 与 lint-staged 一起使用以在暂存的 git 文件上运行 linter，则必须将以下内容添加到项目根目录中的 .lintstagedrc.js 文件中，以便指定 --file 标志的使用。

const path = require('path')
 
const buildEslintCommand = (filenames) =>
  `next lint --fix --file ${filenames
    .map((f) => path.relative(process.cwd(), f))
    .join(' --file ')}`
 
module.exports = {
  '*.{js,jsx,ts,tsx}': [buildEslintCommand],
}

迁移现有配置

推荐的插件规则集

如果您已经在您的应用程序中配置了 ESLint，并且以下任何条件为真

• 您已经安装了一个或多个以下插件（无论是单独安装还是通过其他配置，例如 airbnb 或 react-app）
  • react
  • react-hooks
  • jsx-a11y
  • import
• 您已定义了与 Next.js 中 Babel 配置不同的特定 parserOptions（除非您已自定义您的 Babel 配置，否则不建议这样做）
• 您已安装 eslint-plugin-import 以及 Node.js 和/或 TypeScript 解析器 来处理导入

那么我们建议，如果您更喜欢 eslint-config-next 中配置的这些属性的方式，则删除这些设置；或者直接从 Next.js ESLint 插件扩展

module.exports = {
  extends: [
    //...
    'plugin:@next/next/recommended',
  ],
}

该插件可以在您的项目中正常安装，无需运行 next lint

npm install --save-dev @next/eslint-plugin-next
 
yarn add --dev @next/eslint-plugin-next
 
pnpm add --save-dev @next/eslint-plugin-next
 
bun add --dev @next/eslint-plugin-next

这消除了由于在多个配置中导入相同的插件或解析器而可能发生的冲突或错误的风险。

其他配置

如果您已经使用单独的 ESLint 配置，并且想要包含 eslint-config-next，请确保它在其他配置之后最后扩展。例如

{
  "extends": ["eslint:recommended", "next"]
}

next 配置已经处理了为 parser、plugins 和 settings 属性设置默认值。除非您需要针对您的用例进行不同的配置，否则无需手动重新声明任何这些属性。

如果您包含任何其他可共享的配置，**您需要确保这些属性不会被覆盖或修改**。否则，我们建议删除任何与 next 配置共享行为的配置，或者如上所述直接从 Next.js ESLint 插件扩展。