ESLint 插件

Next.js 提供了一个 ESLint 配置包 eslint-config-next，使你能够轻松地发现应用程序中的常见问题。它包含了 @next/eslint-plugin-next 插件，以及来自 eslint-plugin-react 和 eslint-plugin-react-hooks 的推荐规则集。

该包提供了两种主要配置：

eslint-config-next：包含 Next.js、React 和 React Hooks 规则的基础配置。支持 JavaScript 和 TypeScript 文件。
eslint-config-next/core-web-vitals：包含基础配置中的所有内容，另外将影响 Core Web Vitals 的规则从警告升级为错误。推荐用于大多数项目。

此外，对于 TypeScript 项目：

eslint-config-next/typescript：添加了来自 typescript-eslint 的 TypeScript 特有 Lint 规则。请将其与基础配置或 core-web-vitals 配置一同使用。

设置 ESLint

使用 ESLint CLI（扁平配置）快速开始 Linting：

安装 ESLint 和 Next.js 配置：

bash

pnpm add -D eslint eslint-config-next

bash

npm i -D eslint eslint-config-next

bash

yarn add --dev eslint eslint-config-next

bash

bun add -d eslint eslint-config-next

使用 Next.js 配置创建 eslint.config.mjs：

javascript

import { defineConfig, globalIgnores } from 'eslint/config'
import nextVitals from 'eslint-config-next/core-web-vitals'

const eslintConfig = defineConfig([
  ...nextVitals,
  // Override default ignores of eslint-config-next.
  globalIgnores([
    // Default ignores of eslint-config-next:
    '.next/**',
    'out/**',
    'build/**',
    'next-env.d.ts',
  ]),
])

export default eslintConfig

运行 ESLint：

bash

pnpm exec eslint .

bash

npx eslint .

bash

yarn eslint .

bash

bunx eslint .

参考

eslint-config-next 包包含了以下 ESLint 插件的 recommended 规则集：

规则

包含的 @next/eslint-plugin-next 规则有：

在推荐配置中启用	规则	描述
	@next/next/google-font-display	强制 Google Fonts 的 `font-display` 行为。
	@next/next/google-font-preconnect	确保 Google Fonts 使用 `preconnect`。
	@next/next/inline-script-id	强制带有内联内容的 `next/script` 组件具有 `id` 属性。
	@next/next/next-script-for-ga	使用 Google Analytics 的内联脚本时，推荐使用 `next/script` 组件。
	@next/next/no-assign-module-variable	禁止对 `module` 变量进行赋值。
	@next/next/no-async-client-component	禁止客户端组件（Client Components）成为异步函数。
	@next/next/no-before-interactive-script-outside-document	禁止在 `pages/_document.js` 之外使用 `next/script` 的 `beforeInteractive` 策略。
	@next/next/no-css-tags	禁止手动样式表标签。
	@next/next/no-document-import-in-page	禁止在 `pages/_document.js` 之外导入 `next/document`。
	@next/next/no-duplicate-head	禁止在 `pages/_document.js` 中重复使用 `<Head>`。
	@next/next/no-head-element	禁止使用 `<head>` 元素。
	@next/next/no-head-import-in-document	禁止在 `pages/_document.js` 中使用 `next/head`。
	@next/next/no-html-link-for-pages	禁止使用 `<a>` 元素导航到内部 Next.js 页面。
	@next/next/no-img-element	禁止使用 `<img>` 元素，因为它会导致 LCP 变慢和更高的带宽占用。
	@next/next/no-page-custom-font	禁止仅限于页面的自定义字体。
	@next/next/no-script-component-in-head	禁止在 `next/head` 组件中使用 `next/script`。
	@next/next/no-styled-jsx-in-document	禁止在 `pages/_document.js` 中使用 `styled-jsx`。
	@next/next/no-sync-scripts	禁止同步脚本。
	@next/next/no-title-in-document-head	禁止将 `<title>` 与来自 `next/document` 的 `Head` 组件一起使用。
	@next/next/no-typos	禁止在 Next.js 的数据获取函数中出现常见拼写错误。
	@next/next/no-unwanted-polyfillio	禁止来自 Polyfill.io 的重复 polyfill。

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

next lint 已移除

从 Next.js 16 开始，next lint 已被移除。

作为移除的一部分，你的 Next 配置文件中的 eslint 选项不再需要，可以安全移除。

示例

在 Monorepo 中指定根目录

如果你在 Next.js 未安装在根目录的项目中（例如 monorepo）使用 @next/eslint-plugin-next，你可以通过在 eslint.config.mjs 中使用 settings 属性来告诉 @next/eslint-plugin-next 你的 Next.js 应用程序的位置：

javascript

import { defineConfig } from 'eslint/config'
import eslintNextPlugin from '@next/eslint-plugin-next'

const eslintConfig = defineConfig([
  {
    files: ['**/*.{js,jsx,ts,tsx}'],
    plugins: {
      next: eslintNextPlugin,
    },
    settings: {
      next: {
        rootDir: 'packages/my-app/',
      },
    },
  },
])

export default eslintConfig

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

禁用规则

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

javascript

import { defineConfig, globalIgnores } from 'eslint/config'
import nextVitals from 'eslint-config-next/core-web-vitals'

const eslintConfig = defineConfig([
  ...nextVitals,
  {
    rules: {
      'react/no-unescaped-entities': 'off',
      '@next/next/no-page-custom-font': 'off',
    },
  },
  // Override default ignores of eslint-config-next.
  globalIgnores([
    // Default ignores of eslint-config-next:
    '.next/**',
    'out/**',
    'build/**',
    'next-env.d.ts',
  ]),
])

export default eslintConfig

结合 Core Web Vitals

在你的 ESLint 配置中启用 eslint-config-next/core-web-vitals 配置。

javascript

import { defineConfig, globalIgnores } from 'eslint/config'
import nextVitals from 'eslint-config-next/core-web-vitals'

const eslintConfig = defineConfig([
  ...nextVitals,
  // Override default ignores of eslint-config-next.
  globalIgnores([
    // Default ignores of eslint-config-next:
    '.next/**',
    'out/**',
    'build/**',
    'next-env.d.ts',
  ]),
])

export default eslintConfig

eslint-config-next/core-web-vitals 将 @next/eslint-plugin-next 中的某些 Lint 规则从警告升级为错误，以帮助改进你的 Core Web Vitals 指标。

对于使用 Create Next App 构建的新应用程序，eslint-config-next/core-web-vitals 配置会自动包含。

结合 TypeScript

除了 Next.js ESLint 规则之外，create-next-app --typescript 还会使用 eslint-config-next/typescript 向你的配置中添加 TypeScript 特定的 Lint 规则：

javascript

import { defineConfig, globalIgnores } from 'eslint/config'
import nextVitals from 'eslint-config-next/core-web-vitals'
import nextTs from 'eslint-config-next/typescript'

const eslintConfig = defineConfig([
  ...nextVitals,
  ...nextTs,
  // Override default ignores of eslint-config-next.
  globalIgnores([
    // Default ignores of eslint-config-next:
    '.next/**',
    'out/**',
    'build/**',
    'next-env.d.ts',
  ]),
])

export default eslintConfig

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

结合 Prettier

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

首先，安装依赖：

bash

pnpm add -D eslint-config-prettier

bash

npm i -D eslint-config-prettier

bash

yarn add --dev eslint-config-prettier

bash

bun add -d eslint-config-prettier

然后，将 prettier 添加到你现有的 ESLint 配置中：

javascript

import { defineConfig, globalIgnores } from 'eslint/config'
import nextVitals from 'eslint-config-next/core-web-vitals'
import prettier from 'eslint-config-prettier/flat'

const eslintConfig = defineConfig([
  ...nextVitals,
  prettier,
  // Override default ignores of eslint-config-next.
  globalIgnores([
    // Default ignores of eslint-config-next:
    '.next/**',
    'out/**',
    'build/**',
    'next-env.d.ts',
  ]),
])

export default eslintConfig

对暂存文件运行 Lint

如果你想将 ESLint 与 lint-staged 一起使用，对暂存的 Git 文件运行 Linter，请将以下内容添加到项目根目录的 .lintstagedrc.js 文件中：

javascript

const path = require('path')

const buildEslintCommand = (filenames) =>
  `eslint --fix ${filenames
    .map((f) => `"${path.relative(process.cwd(), f)}"`)
    .join(' ')}`

module.exports = {
  '*.{js,jsx,ts,tsx}': [buildEslintCommand],
}

迁移现有配置

如果你的应用程序中已经配置了 ESLint，则根据你的设置，有两种方法可以集成 Next.js 的 Lint 规则。

直接使用插件

如果你已配置以下任何项，请直接使用 @next/eslint-plugin-next：

单独安装或通过其他配置（如 airbnb 或 react-app）安装的冲突插件：
- react
- react-hooks
- jsx-a11y
- import
与 Next.js 默认值不同的自定义 parserOptions（仅当你自定义了 Babel 配置时）
带有自定义 Node.js 和/或 TypeScript 解析器的 eslint-plugin-import

在这些情况下，请直接使用 @next/eslint-plugin-next 以避免冲突：

首先，安装插件：

bash

pnpm add -D @next/eslint-plugin-next

bash

npm i -D @next/eslint-plugin-next

bash

yarn add --dev @next/eslint-plugin-next

bash

bun add -d @next/eslint-plugin-next

然后将其添加到你的 ESLint 配置中：

javascript

import { defineConfig } from 'eslint/config'
import nextPlugin from '@next/eslint-plugin-next'

const eslintConfig = defineConfig([
  // Your other configurations...
  {
    files: ['**/*.{js,jsx,ts,tsx}'],
    plugins: {
      '@next/next': nextPlugin,
    },
    rules: {
      ...nextPlugin.configs.recommended.rules,
    },
  },
])

export default eslintConfig

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

添加到现有配置

如果你将 Next.js 添加到现有的 ESLint 设置中，请将 Next.js 配置扩展到你的数组中：

javascript

import nextConfig from 'eslint-config-next/core-web-vitals'
// Your other config imports...

const eslintConfig = [
  // Your other configurations...
  ...nextConfig,
]

export default eslintConfig

当你扩展 ...nextConfig 时，你添加了多个配置对象，它们包含文件模式、插件、规则、忽略项和解析器设置。ESLint 按顺序应用配置，因此后面的规则可以覆盖匹配文件的早期规则。

须知： 这种方法适用于简单的设置。如果你有一个复杂的现有配置，其中包含特定的文件模式或冲突的插件配置，请考虑直接使用插件（如上所示）以获得更精细的控制。

版本	变更
`v16.0.0`	`next lint` 和 `next.config.js` 中的 `eslint` 选项已移除，转而使用 ESLint CLI。提供了一个 codemod 来帮助你迁移。

该包提供了两种主要配置：

eslint-config-next：包含 Next.js、React 和 React Hooks 规则的基础配置。支持 JavaScript 和 TypeScript 文件。
eslint-config-next/core-web-vitals：包含基础配置中的所有内容，另外将影响 Core Web Vitals 的规则从警告升级为错误。推荐用于大多数项目。

此外，对于 TypeScript 项目：

eslint-config-next/typescript：添加了来自 typescript-eslint 的 TypeScript 特有 Lint 规则。请将其与基础配置或 core-web-vitals 配置一同使用。

设置 ESLint

使用 ESLint CLI（扁平配置）快速开始 Linting：

安装 ESLint 和 Next.js 配置：

bash

pnpm add -D eslint eslint-config-next

bash

npm i -D eslint eslint-config-next

bash

yarn add --dev eslint eslint-config-next

bash

bun add -d eslint eslint-config-next

使用 Next.js 配置创建 eslint.config.mjs：

javascript

import { defineConfig, globalIgnores } from 'eslint/config'
import nextVitals from 'eslint-config-next/core-web-vitals'

const eslintConfig = defineConfig([
  ...nextVitals,
  // Override default ignores of eslint-config-next.
  globalIgnores([
    // Default ignores of eslint-config-next:
    '.next/**',
    'out/**',
    'build/**',
    'next-env.d.ts',
  ]),
])

export default eslintConfig

运行 ESLint：

bash

pnpm exec eslint .

bash

npx eslint .

bash

yarn eslint .

bash

bunx eslint .

参考

eslint-config-next 包包含了以下 ESLint 插件的 recommended 规则集：

规则

包含的 @next/eslint-plugin-next 规则有：

在推荐配置中启用	规则	描述
	@next/next/google-font-display	强制 Google Fonts 的 `font-display` 行为。
	@next/next/google-font-preconnect	确保 Google Fonts 使用 `preconnect`。
	@next/next/inline-script-id	强制带有内联内容的 `next/script` 组件具有 `id` 属性。
	@next/next/next-script-for-ga	使用 Google Analytics 的内联脚本时，推荐使用 `next/script` 组件。
	@next/next/no-assign-module-variable	禁止对 `module` 变量进行赋值。
	@next/next/no-async-client-component	禁止客户端组件（Client Components）成为异步函数。
	@next/next/no-before-interactive-script-outside-document	禁止在 `pages/_document.js` 之外使用 `next/script` 的 `beforeInteractive` 策略。
	@next/next/no-css-tags	禁止手动样式表标签。
	@next/next/no-document-import-in-page	禁止在 `pages/_document.js` 之外导入 `next/document`。
	@next/next/no-duplicate-head	禁止在 `pages/_document.js` 中重复使用 `<Head>`。
	@next/next/no-head-element	禁止使用 `<head>` 元素。
	@next/next/no-head-import-in-document	禁止在 `pages/_document.js` 中使用 `next/head`。
	@next/next/no-html-link-for-pages	禁止使用 `<a>` 元素导航到内部 Next.js 页面。
	@next/next/no-img-element	禁止使用 `<img>` 元素，因为它会导致 LCP 变慢和更高的带宽占用。
	@next/next/no-page-custom-font	禁止仅限于页面的自定义字体。
	@next/next/no-script-component-in-head	禁止在 `next/head` 组件中使用 `next/script`。
	@next/next/no-styled-jsx-in-document	禁止在 `pages/_document.js` 中使用 `styled-jsx`。
	@next/next/no-sync-scripts	禁止同步脚本。
	@next/next/no-title-in-document-head	禁止将 `<title>` 与来自 `next/document` 的 `Head` 组件一起使用。
	@next/next/no-typos	禁止在 Next.js 的数据获取函数中出现常见拼写错误。
	@next/next/no-unwanted-polyfillio	禁止来自 Polyfill.io 的重复 polyfill。

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

next lint 已移除

从 Next.js 16 开始，next lint 已被移除。

作为移除的一部分，你的 Next 配置文件中的 eslint 选项不再需要，可以安全移除。

示例

在 Monorepo 中指定根目录

javascript

import { defineConfig } from 'eslint/config'
import eslintNextPlugin from '@next/eslint-plugin-next'

const eslintConfig = defineConfig([
  {
    files: ['**/*.{js,jsx,ts,tsx}'],
    plugins: {
      next: eslintNextPlugin,
    },
    settings: {
      next: {
        rootDir: 'packages/my-app/',
      },
    },
  },
])

export default eslintConfig

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

禁用规则

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

javascript

import { defineConfig, globalIgnores } from 'eslint/config'
import nextVitals from 'eslint-config-next/core-web-vitals'

const eslintConfig = defineConfig([
  ...nextVitals,
  {
    rules: {
      'react/no-unescaped-entities': 'off',
      '@next/next/no-page-custom-font': 'off',
    },
  },
  // Override default ignores of eslint-config-next.
  globalIgnores([
    // Default ignores of eslint-config-next:
    '.next/**',
    'out/**',
    'build/**',
    'next-env.d.ts',
  ]),
])

export default eslintConfig

结合 Core Web Vitals

在你的 ESLint 配置中启用 eslint-config-next/core-web-vitals 配置。

javascript

import { defineConfig, globalIgnores } from 'eslint/config'
import nextVitals from 'eslint-config-next/core-web-vitals'

const eslintConfig = defineConfig([
  ...nextVitals,
  // Override default ignores of eslint-config-next.
  globalIgnores([
    // Default ignores of eslint-config-next:
    '.next/**',
    'out/**',
    'build/**',
    'next-env.d.ts',
  ]),
])

export default eslintConfig

eslint-config-next/core-web-vitals 将 @next/eslint-plugin-next 中的某些 Lint 规则从警告升级为错误，以帮助改进你的 Core Web Vitals 指标。

对于使用 Create Next App 构建的新应用程序，eslint-config-next/core-web-vitals 配置会自动包含。

结合 TypeScript

除了 Next.js ESLint 规则之外，create-next-app --typescript 还会使用 eslint-config-next/typescript 向你的配置中添加 TypeScript 特定的 Lint 规则：

javascript

import { defineConfig, globalIgnores } from 'eslint/config'
import nextVitals from 'eslint-config-next/core-web-vitals'
import nextTs from 'eslint-config-next/typescript'

const eslintConfig = defineConfig([
  ...nextVitals,
  ...nextTs,
  // Override default ignores of eslint-config-next.
  globalIgnores([
    // Default ignores of eslint-config-next:
    '.next/**',
    'out/**',
    'build/**',
    'next-env.d.ts',
  ]),
])

export default eslintConfig

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

结合 Prettier

首先，安装依赖：

bash

pnpm add -D eslint-config-prettier

bash

npm i -D eslint-config-prettier

bash

yarn add --dev eslint-config-prettier

bash

bun add -d eslint-config-prettier

然后，将 prettier 添加到你现有的 ESLint 配置中：

javascript

import { defineConfig, globalIgnores } from 'eslint/config'
import nextVitals from 'eslint-config-next/core-web-vitals'
import prettier from 'eslint-config-prettier/flat'

const eslintConfig = defineConfig([
  ...nextVitals,
  prettier,
  // Override default ignores of eslint-config-next.
  globalIgnores([
    // Default ignores of eslint-config-next:
    '.next/**',
    'out/**',
    'build/**',
    'next-env.d.ts',
  ]),
])

export default eslintConfig

对暂存文件运行 Lint

如果你想将 ESLint 与 lint-staged 一起使用，对暂存的 Git 文件运行 Linter，请将以下内容添加到项目根目录的 .lintstagedrc.js 文件中：

javascript

const path = require('path')

const buildEslintCommand = (filenames) =>
  `eslint --fix ${filenames
    .map((f) => `"${path.relative(process.cwd(), f)}"`)
    .join(' ')}`

module.exports = {
  '*.{js,jsx,ts,tsx}': [buildEslintCommand],
}

迁移现有配置

如果你的应用程序中已经配置了 ESLint，则根据你的设置，有两种方法可以集成 Next.js 的 Lint 规则。

直接使用插件

如果你已配置以下任何项，请直接使用 @next/eslint-plugin-next：

单独安装或通过其他配置（如 airbnb 或 react-app）安装的冲突插件：
- react
- react-hooks
- jsx-a11y
- import
与 Next.js 默认值不同的自定义 parserOptions（仅当你自定义了 Babel 配置时）
带有自定义 Node.js 和/或 TypeScript 解析器的 eslint-plugin-import

在这些情况下，请直接使用 @next/eslint-plugin-next 以避免冲突：

首先，安装插件：

bash

pnpm add -D @next/eslint-plugin-next

bash

npm i -D @next/eslint-plugin-next

bash

yarn add --dev @next/eslint-plugin-next

bash

bun add -d @next/eslint-plugin-next

然后将其添加到你的 ESLint 配置中：

javascript

import { defineConfig } from 'eslint/config'
import nextPlugin from '@next/eslint-plugin-next'

const eslintConfig = defineConfig([
  // Your other configurations...
  {
    files: ['**/*.{js,jsx,ts,tsx}'],
    plugins: {
      '@next/next': nextPlugin,
    },
    rules: {
      ...nextPlugin.configs.recommended.rules,
    },
  },
])

export default eslintConfig

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

添加到现有配置

如果你将 Next.js 添加到现有的 ESLint 设置中，请将 Next.js 配置扩展到你的数组中：

javascript

import nextConfig from 'eslint-config-next/core-web-vitals'
// Your other config imports...

const eslintConfig = [
  // Your other configurations...
  ...nextConfig,
]

export default eslintConfig

须知： 这种方法适用于简单的设置。如果你有一个复杂的现有配置，其中包含特定的文件模式或冲突的插件配置，请考虑直接使用插件（如上所示）以获得更精细的控制。

版本	变更
`v16.0.0`	`next lint` 和 `next.config.js` 中的 `eslint` 选项已移除，转而使用 ESLint CLI。提供了一个 codemod 来帮助你迁移。

文档导航

设置 ESLint

参考

规则

示例

在 Monorepo 中指定根目录

禁用规则

结合 Core Web Vitals

结合 TypeScript

结合 Prettier

对暂存文件运行 Lint

迁移现有配置

直接使用插件

添加到现有配置

设置 ESLint

参考

规则

示例

在 Monorepo 中指定根目录

禁用规则

结合 Core Web Vitals

结合 TypeScript

结合 Prettier

对暂存文件运行 Lint

迁移现有配置

直接使用插件

添加到现有配置