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 文件。

现在您可以在需要捕获错误时随时运行 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 插件 eslint-plugin-next，已捆绑在基础配置中，可捕获 Next.js 应用中的常见问题和错误。完整规则集如下：

在推荐配置中启用

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

自定义设置

rootDir

如果您在 Next.js 未安装在根目录的项目（如 monorepo）中使用 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'], // 仅在生产构建 (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 入口点。

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 > 配置。

与其他工具一起使用

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 插件。