Next.js 中文网

主题

ESLint ​

Next.js 提供了一个 ESLint 配置包 eslint-config-next，可以轻松捕获应用中的常见问题。它包含 @next/eslint-plugin-next 插件以及来自 eslint-plugin-react 和 eslint-plugin-react-hooks 的推荐规则集。

¥Next.js provides an ESLint configuration package, eslint-config-next, that makes it easy to catch common issues in your application. It includes the @next/eslint-plugin-next plugin along with recommended rule-sets from eslint-plugin-react and eslint-plugin-react-hooks.

该软件包提供两种主要配置：

¥The package provides two main configurations:

  • eslint-config-next：基于 Next.js、React 和 React Hooks 规则的基本配置。同时支持 JavaScript 和 TypeScript 文件。

    ¥eslint-config-next: Base configuration with Next.js, React, and React Hooks rules. Supports both JavaScript and TypeScript files.

  • eslint-config-next/core-web-vitals：包含基本配置的所有内容，以及将影响 核心网络生命力 的规则从警告升级为错误。推荐用于大多数项目。

    ¥eslint-config-next/core-web-vitals: Includes everything from the base config, plus upgrades rules that impact Core Web Vitals from warnings to errors. Recommended for most projects.

此外，对于 TypeScript 项目：

¥Additionally, for TypeScript projects:

  • eslint-config-next/typescript：添加来自 typescript-eslint 的 TypeScript 特定代码检查规则。将其与基础配置或 core-web-vitals 配置一起使用。

    ¥eslint-config-next/typescript: Adds TypeScript-specific linting rules from typescript-eslint. Use this alongside the base or core-web-vitals config.

设置 ESLint ​

¥Setup ESLint

使用 ESLint CLI（扁平配置）快速进行代码检查：

¥Get linting working quickly with the ESLint CLI (flat config):

  1. 安装 ESLint 和 Next.js 配置：

    ¥Install ESLint and the Next.js config:

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

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

    ¥Create eslint.config.mjs with the Next.js config:

  2. 运行 ESLint：

    ¥Run ESLint:

bash
   pnpm exec eslint .
bash
   npx eslint .
bash
   yarn eslint .
bash
   bunx eslint .

参考 ​

¥Reference

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

¥The eslint-config-next package includes the recommended rule-sets from the following ESLint plugins:

规则 ​

¥Rules

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

¥The @next/eslint-plugin-next rules included are:

在推荐配置中启用规则描述
@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 的重复填充。

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

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

`next lint` removal

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

¥Starting with Next.js 16, next lint is removed.

移除过程中，Next.js 配置文件中的 eslint 选项不再需要，可以安全地移除。

¥As part of the removal, the eslint option in your Next config file is no longer needed and can be safely removed.

示例 ​

¥Examples

在指定根目录中 monorepo ​

¥Specifying a root directory within a monorepo

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

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

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.

禁用规则 ​

¥Disabling rules

如果你想修改或禁用受支持的插件（react、react-hooks、next）提供的任何规则，你可以使用 eslint.config.mjs 中的 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 eslint.config.mjs:

使用核心 Web 生命力 ​

¥With Core Web Vitals

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

¥Enable the eslint-config-next/core-web-vitals configuration in your ESLint config.

eslint-config-next/core-web-vitals 将 @next/eslint-plugin-next 中的某些 lint 规则从警告升级为错误，以帮助改善你的 核心网络生命力 指标。

¥eslint-config-next/core-web-vitals upgrades certain lint rules in @next/eslint-plugin-next from warnings to errors to help improve your Core Web Vitals metrics.

使用 创建 Next 应用 构建的新应用会自动包含 eslint-config-next/core-web-vitals 配置。

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

使用 TypeScript ​

¥With TypeScript

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

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

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

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

使用 Prettier ​

¥With 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:

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

¥Then, add prettier to your existing ESLint config:

在暂存文件上运行 lint ​

¥Running lint on staged files

如果你想使用 ESLint 和 lint-staged 对暂存的 Git 文件运行代码检查器，请将以下内容添加到项目根目录下的 .lintstagedrc.js 文件中：

¥If you would like to use ESLint with lint-staged to run the linter on staged git files, add the following to the .lintstagedrc.js file in the root of your project:

迁移现有配置 ​

¥Migrating existing config

如果你已在应用中配置了 ESLint，则有两种方法可以集成 Next.js linting 规则，具体取决于你的设置。

¥If you already have ESLint configured in your application, there are two approaches to integrate Next.js linting rules, depending on your setup.

直接使用插件 ​

¥Using the plugin directly

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

¥Use @next/eslint-plugin-next directly if you have any of the following already configured:

  • 单独安装或通过其他配置（例如 airbnb 或 react-app）安装的冲突插件：

    ¥Conflicting plugins installed separately or through another config (such as airbnb or react-app):

    • react

    • react-hooks

    • jsx-a11y

    • import

  • 自定义 parserOptions 与 Next.js 默认设置不同（仅当你有 定制你的 Babel 配置 时）。

    ¥Custom parserOptions different from Next.js defaults (only if you have customized your Babel configuration)

  • eslint-plugin-import 与自定义 Node.js 和/或 TypeScript resolvers 兼容。

    ¥eslint-plugin-import with custom Node.js and/or TypeScript resolvers

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

¥In these cases, use @next/eslint-plugin-next directly to avoid conflicts:

首先，安装插件：

¥First, install the plugin:

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

¥Then add it to your ESLint config:

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

¥This approach eliminates the risk of collisions or errors that can occur when the same plugins or parsers are imported across multiple configurations.

添加到现有配置 ​

¥Adding to existing config

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

¥If you're adding Next.js to an existing ESLint setup, spread the Next.js config into your array:

当你扩展 ...nextConfig 时，你实际上是在添加多个配置对象，这些对象包含文件模式、插件、规则、忽略项和解析器设置。ESLint 按顺序应用配置，因此后续规则可以覆盖先前匹配文件的规则。

¥When you spread ...nextConfig, you're adding multiple config objects that include file patterns, plugins, rules, ignores, and parser settings. ESLint applies configs in order, so later rules can override earlier ones for matching files.

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

¥Good to know: This approach works well for straightforward setups. If you have a complex existing config with specific file patterns or plugin configurations that conflict, consider using the plugin directly (as shown above) for more granular control.

版本更改
v16.0.0next lint 和 eslint 的 next.config.js 选项已被移除，取而代之的是 ESLint CLI。提供 codemod 以帮助你进行迁移。