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 时的推荐配置。

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

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

  {
    "extends": "next"
  }

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

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

现在您可以在需要运行 ESLint 检查错误时执行 next lint。ESLint 设置完成后，每次构建 (next build) 时也会自动运行。错误会导致构建失败，而警告则不会。

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

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

ESLint 配置

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

如需将 eslint-config-next 与其他 ESLint 配置一起使用，请参阅 额外配置 部分了解如何避免冲突。

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

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

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

ESLint 插件

Next.js 提供的 eslint-plugin-next 插件已内置在基础配置中，可用于捕获 Next.js 应用中的常见问题。完整规则集如下：

在推荐配置中启用

如果您的应用中已配置 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/*/"）或路径/通配符数组。

检查自定义目录和文件

默认情况下，Next.js 会对 pages/、app/、components/、lib/ 和 src/ 目录中的所有文件运行 ESLint。但您可以通过 next.config.js 中的 eslint 配置的 dirs 选项指定生产构建时要检查的目录：

module.exports = {
  eslint: {
    dirs: ['pages', 'utils'], // 生产构建 (next build) 时仅对 'pages' 和 'utils' 目录运行 ESLint
  },
}

类似地，next lint 可使用 --dir 和 --file 标志来检查特定目录和文件：

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

核心 Web 指标

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

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

next/core-web-vitals 会将 eslint-plugin-next 中默认作为警告的、影响 核心 Web 指标 的规则升级为错误。

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

与其他工具配合使用

Prettier

ESLint 也包含代码格式化规则，可能与现有的 Prettier 设置冲突。我们建议在 ESLint 配置中包含 eslint-config-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 文件运行检查器，需在项目根目录的 .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 插件进行扩展。