ESLint

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

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

然后运行npm run lint 或 yarn lint:

yarn lint

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

yarn lint

您将看到如下提示：

? 您想如何配置 ESLint？

❯ Strict (recommended)
Base
Cancel

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

Strict：包含 Next.js 的基础 ESLint 配置以及更严格的 Core Web Vitals 规则集。这是第一次设置 ESLint 时的推荐配置。

Strict: 包含 Next.js 的基础 ESLint 配置以及更严格的Core Web Vitals rule-set。这是第一次设置 ESLint 时的推荐配置。
```
{
  "extends": "next/core-web-vitals"
}
```
Base: 包含 Next.js 的基础 ESLint 配置。
```
{
  "extends": "next"
}
```
Cancel: 不包含任何 ESLint 配置。仅当您计划自行设置自定义 ESLint 配置时选择此项。

如果选择了其中的任一配置选项，Next.js 会自动在您的应用中安装 eslint 和 eslint-config-next 作为依赖项，并在项目根目录创建 .eslintrc.json 文件，包含您选择的配置。

现在，您可以通过 next lint 运行 ESLint 来捕获错误。一旦设置了 ESLint，它还会在每次构建时（next build）自动运行。错误将导致构建失败，而警告不会。

如果您不希望在next build时运行 ESLint，请参阅忽略 ESLint文档。

我们建议使用适当的集成工具在开发期间直接在代码编辑器中查看警告和错误。

ESLint 配置

如果您希望将 eslint-config-next 与其他 ESLint 配置结合使用，请参阅其他配置部分，了解如何在不引发冲突的情况下进行操作。

默认配置(eslint-config-next)包含了在 Next.js 中拥有最佳 linting 体验所需的全部内容。如果您的应用程序中尚未配置 ESLint，我们建议使用next lint来设置 ESLint 并应用此配置。

eslint-config-next使用了以下 ESLint 插件中推荐规则集：

这些规则优先于 next.config.js 中的配置。

ESLint 插件

Next.js 提供了一个 ESLint 插件，eslint-plugin-next，该插件已包含在基础配置中，可以捕捉 Next.js 应用中的常见问题。完整的规则集如下：

✔️ 在推荐配置中启用

	Rule	Description
✔️	@next/next/google-font-display	Enforce font-display behavior with Google Fonts.
✔️	@next/next/google-font-preconnect	Ensure `preconnect` is used with Google Fonts.
✔️	@next/next/inline-script-id	Enforce `id` attribute on `next/script` components with inline content.
✔️	@next/next/next-script-for-ga	Prefer `next/script` component when using the inline script for Google Analytics.
✔️	@next/next/no-assign-module-variable	Prevent assignment to the `module` variable.
✔️	@next/next/no-async-client-component	Prevent client components from being async functions.
✔️	@next/next/no-before-interactive-script-outside-document	Prevent usage of `next/script`'s `beforeInteractive` strategy outside of `pages/_document.js`.
✔️	@next/next/no-css-tags	Prevent manual stylesheet tags.
✔️	@next/next/no-document-import-in-page	Prevent importing `next/document` outside of `pages/_document.js`.
✔️	@next/next/no-duplicate-head	Prevent duplicate usage of `<Head>` in `pages/_document.js`.
✔️	@next/next/no-head-element	Prevent usage of `<head>` element.
✔️	@next/next/no-head-import-in-document	Prevent usage of `next/head` in `pages/_document.js`.
✔️	@next/next/no-html-link-for-pages	Prevent usage of `<a>` elements to navigate to internal Next.js pages.
✔️	@next/next/no-img-element	Prevent usage of `<img>` element due to slower LCP and higher bandwidth.
✔️	@next/next/no-page-custom-font	Prevent page-only custom fonts.
✔️	@next/next/no-script-component-in-head	Prevent usage of `next/script` in `next/head` component.
✔️	@next/next/no-styled-jsx-in-document	Prevent usage of `styled-jsx` in `pages/_document.js`.
✔️	@next/next/no-sync-scripts	Prevent synchronous scripts.
✔️	@next/next/no-title-in-document-head	Prevent usage of `<title>` with `Head` component from `next/document`.
✔️	@next/next/no-typos	Prevent common typos in Next.js's data fetching functions
✔️	@next/next/no-unwanted-polyfillio	Prevent duplicate polyfills from Polyfill.io.

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

自定义设置

`rootDir`

如果您在 Next.js 未安装在根目录的项目（例如 monorepo）中使用eslint-plugin-next，可以通过 .eslintrc 中的 settings 属性指定 Next.js 应用的位置：

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

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

自定义目录和文件的 Linting

默认情况下，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对特定目录和文件进行 lint：

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

缓存

为提高性能，ESLint 处理的文件信息默认会被缓存，存储在.next/cache中，或者存储在您定义的构建目录中。如果您包含的 ESLint 规则依赖于不止一个源文件的内容，并且需要禁用缓存，可以通过 --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"
  }
}

Core Web Vitals

当您第一次运行next lint并选择 strict 配置时，next/core-web-vitals规则集会启用。

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

next/core-web-vitals会将一些默认作为警告的规则提升为错误，这些规则可能会影响Core Web Vitals。

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

TypeScript

除了 Next.js 的 ESLint 规则外，'create-next-app——typescript'也会在您的配置中添加带有'next/typescript'的 typescript 特有的 lint 规则:

{
  "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

然后，在现有的 ESLint 配置中添加 prettier：

{
  "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 配置并希望包含eslint-config-next，请确保它是在其他配置之后扩展的。例如：

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

next配置已经处理了parser、plugins 和 settings 属性的默认值，除非您需要不同的配置，否则无需手动重新声明这些属性。

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

ESLint 配置​

ESLint 插件​

自定义设置​

rootDir​

自定义目录和文件的 Linting​

缓存​

禁用规则​

Core Web Vitals​

TypeScript​

与其他工具一起使用​

Prettier​

lint-staged​

迁移现有配置​

推荐的插件规则集​

其他配置​