ESLint

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

¥Next.js provides an integrated ESLint experience out of the box. Add next lint as a script to package.json:

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

然后运行 npm run lint 或 yarn lint：

¥Then run npm run lint or yarn lint:

yarn lint

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

¥If you don't already have ESLint configured in your application, you will be guided through the installation and configuration process.

yarn lint

你会看到这样的提示：

¥You'll see a prompt like this:

？ 你希望如何配置 ESLint？

¥? How would you like to configure ESLint?

❯ 严格（推荐）基础取消

¥❯ Strict (recommended)\ Base\ Cancel

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

¥One of the following three options can be selected:

• 严格的：包括 Next.js 的基本 ESLint 配置以及更严格的 核心 Web Vitals 规则集。这是首次设置 ESLint 的开发者的推荐配置。

  ¥Strict: Includes Next.js' base ESLint configuration along with a stricter Core Web Vitals rule-set. This is the recommended configuration for developers setting up ESLint for the first time.

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

• 根据：包括 Next.js 的基本 ESLint 配置。

  ¥Base: Includes Next.js' base ESLint configuration.

  {
    "extends": "next"
  }

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

  ¥Cancel: Does not include any ESLint configuration. Only select this option if you plan on setting up your own custom ESLint configuration.

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

¥If either of the two configuration options are selected, Next.js will automatically install eslint and eslint-config-next as dependencies in your application and create an .eslintrc.json file in the root of your project that includes your selected configuration.

现在，你每次想要运行 ESLint 来捕获错误时都可以运行 next lint。一旦 ESLint 设置完毕，它也会在每次构建 (next build) 期间自动运行。错误将使构建失败，而警告则不会。

¥You can now run next lint every time you want to run ESLint to catch errors. Once ESLint has been set up, it will also automatically run during every build (next build). Errors will fail the build, while warnings will not.

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

¥If you do not want ESLint to run during next build, refer to the documentation for Ignoring ESLint.

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

¥We recommend using an appropriate integration to view warnings and errors directly in your code editor during development.

ESLint 配置

¥ESLint Config

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

¥The default configuration (eslint-config-next) includes everything you need to have an optimal out-of-the-box linting experience in Next.js. If you do not have ESLint already configured in your application, we recommend using next lint to set up ESLint along with this configuration.

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

¥If you would like to use eslint-config-next along with other ESLint configurations, refer to the Additional Configurations section to learn how to do so without causing any conflicts.

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

¥Recommended rule-sets from the following ESLint plugins are all used within eslint-config-next:

• eslint-plugin-react

• eslint-plugin-react-hooks

• eslint-plugin-next

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

¥This will take precedence over the configuration from next.config.js.

ESLint 插件

¥ESLint Plugin

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

¥Next.js provides an ESLint plugin, eslint-plugin-next, already bundled within the base configuration that makes it possible to catch common issues and problems in a Next.js application. The full set of rules is as follows:

在推荐配置中启用

¥Enabled in the recommended configuration

	规则	描述
	@next/next/google-font-display	使用 Google Fonts 强制执行字体显示行为。
	@next/next/google-font-preconnect	确保 preconnect 与 Google 字体一起使用。
	@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	防止客户端组件成为异步函数。
	@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	由于 LCP 较慢和带宽较高，请防止使用 <img> 元素。
	@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 的重复填充。

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

¥If you already have ESLint configured in your application, we recommend extending from this plugin directly instead of including eslint-config-next unless a few conditions are met. Refer to the Recommended Plugin Ruleset to learn more.

自定义设置

¥Custom Settings

rootDir

如果你在根目录中未安装 Next.js 的项目（例如 monorepo）中使用 eslint-plugin-next，则可以使用 .eslintrc 中的 settings 属性告诉 eslint-plugin-next 在哪里找到 Next.js 应用：

¥If you're using eslint-plugin-next in a project where Next.js isn't installed in your root directory (such as a monorepo), you can tell eslint-plugin-next where to find your Next.js application using the settings property in your .eslintrc:

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

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

¥rootDir can be a path (relative or absolute), a glob (i.e. "packages/*/"), or an array of paths and/or globs.

检查自定义目录和文件

¥Linting Custom Directories and Files

默认情况下，Next.js 将为 pages/、app/、components/、lib/ 和 src/ 目录中的所有文件运行 ESLint。但是，你可以使用 next.config.js 中 eslint 配置中的 dirs 选项指定哪些目录用于生产构建：

¥By default, Next.js will run ESLint for all files in the pages/, app/, components/, lib/, and src/ directories. However, you can specify which directories using the dirs option in the eslint config in next.config.js for production builds:

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 检测：

¥Similarly, the --dir and --file flags can be used for next lint to lint specific directories and files:

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

缓存

¥Caching

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

¥To improve performance, information of files processed by ESLint are cached by default. This is stored in .next/cache or in your defined build directory. If you include any ESLint rules that depend on more than the contents of a single source file and need to disable the cache, use the --no-cache flag with next lint.

next lint --no-cache

禁用规则

¥Disabling Rules

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

¥If you would like to modify or disable any rules provided by the supported plugins (react, react-hooks, next), you can directly change them using the rules property in your .eslintrc:

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

核心网络生命力

¥Core Web Vitals

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

¥The next/core-web-vitals rule set is enabled when next lint is run for the first time and the strict option is selected.

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

next/core-web-vitals 将 eslint-plugin-next 更新为在许多规则上出错，如果这些规则影响 核心网络生命力，则默认情况下会发出警告。

¥next/core-web-vitals updates eslint-plugin-next to error on a number of rules that are warnings by default if they affect Core Web Vitals.

对于使用 创建 Next 应用 构建的新应用，会自动包含 next/core-web-vitals 入口点。

¥The next/core-web-vitals entry point is automatically included for new applications built with Create Next App.

TypeScript

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

¥In addition to the Next.js ESLint rules, create-next-app --typescript will also add TypeScript-specific lint rules with next/typescript to your config:

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

这些规则基于 plugin:@typescript-eslint/recommended。详细信息请参见 typescript-eslint > 配置。

¥Those rules are based on plugin:@typescript-eslint/recommended. See typescript-eslint > Configs for more details.

与其他工具一起使用

¥Usage With Other Tools

Prettier

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

¥ESLint also contains code formatting rules, which can conflict with your existing Prettier setup. We recommend including eslint-config-prettier in your ESLint config to make ESLint and Prettier work together.

首先，安装依赖：

¥First, install the dependency:

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 配置中：

¥Then, add prettier to your existing ESLint config:

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

lint-staged

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

¥If you would like to use next lint with lint-staged to run the linter on staged git files, you'll have to add the following to the .lintstagedrc.js file in the root of your project in order to specify usage of the --file flag.

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],
}

迁移现有配置

¥Migrating Existing Config

推荐的插件规则集

¥Recommended Plugin Ruleset

如果你已在应用中配置了 ESLint，并且满足以下任一条件：

¥If you already have ESLint configured in your application and any of the following conditions are true:

• 你已经安装了以下一个或多个插件（单独安装或通过不同的配置（例如 airbnb 或 react-app））：

  ¥You have one or more of the following plugins already installed (either separately or through a different config such as airbnb or react-app):

  • react

  • react-hooks

  • jsx-a11y

  • import

• 你定义了与 Next.js 中 Babel 的配置方式不同的特定 parserOptions（除非你有 定制你的 Babel 配置，否则不建议这样做）

  ¥You've defined specific parserOptions that are different from how Babel is configured within Next.js (this is not recommended unless you have customized your Babel configuration)

• 你安装了 eslint-plugin-import，并定义了 Node.js 和/或 TypeScript resolvers 来处理导入

  ¥You have eslint-plugin-import installed with Node.js and/or TypeScript resolvers defined to handle imports

然后，如果你更喜欢在 eslint-config-next 中配置这些属性，我们建议你删除这些设置，或者直接从 Next.js ESLint 插件扩展：

¥Then we recommend either removing these settings if you prefer how these properties have been configured within eslint-config-next or extending directly from the Next.js ESLint plugin instead:

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

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

¥The plugin can be installed normally in your project without needing to run 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

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

¥This eliminates the risk of collisions or errors that can occur due to importing the same plugin or parser across multiple configurations.

附加配置

¥Additional Configurations

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

¥If you already use a separate ESLint configuration and want to include eslint-config-next, ensure that it is extended last after other configurations. For example:

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

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

¥The next configuration already handles setting default values for the parser, plugins and settings properties. There is no need to manually re-declare any of these properties unless you need a different configuration for your use case.

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

¥If you include any other shareable configurations, you will need to make sure that these properties are not overwritten or modified. Otherwise, we recommend removing any configurations that share behavior with the next configuration or extending directly from the Next.js ESLint plugin as mentioned above.