跳到主要内容

ESLint 插件

Next.js 提供了一个 ESLint 插件，eslint-plugin-next，已经捆绑在基础配置中，可以捕获 Next.js 应用程序中的常见问题和错误。

参考​

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

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

规则​

完整的规则集如下：

在推荐配置中启用规则描述
✅@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防止客户端组件成为异步函数。
✅@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防止在 next/document 的 Head 组件中使用 <title>。
✅@next/next/no-typos防止 Next.js 数据获取函数 中的常见拼写错误
✅@next/next/no-unwanted-polyfillio防止来自 Polyfill.io 的重复 polyfill。

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

示例​

对自定义目录和文件进行 lint​

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

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

类似地，--dir 和 --file 标志可以与 next lint 一起使用来对特定目录和文件进行 lint：

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

在 monorepo 中指定根目录​

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

eslint.config.mjs
import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname 在 Node.js v20.11.0 之后可用
  baseDirectory: import.meta.dirname,
})

const eslintConfig = [
  ...compat.config({
    extends: ['next'],
    settings: {
      next: {
        rootDir: 'packages/my-app/',
      },
    },
  }),
]

export default eslintConfig

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

禁用缓存​

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

Terminal
next lint --no-cache

禁用规则​

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

eslint.config.mjs
import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname 在 Node.js v20.11.0 之后可用
  baseDirectory: import.meta.dirname,
})

const eslintConfig = [
  ...compat.config({
    extends: ['next'],
    rules: {
      'react/no-unescaped-entities': 'off',
      '@next/next/no-page-custom-font': 'off',
    },
  }),
]

export default eslintConfig

与 Core Web Vitals 一起使用​

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

eslint.config.mjs
import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname 在 Node.js v20.11.0 之后可用
  baseDirectory: import.meta.dirname,
})

const eslintConfig = [
  ...compat.config({
    extends: ['next/core-web-vitals'],
  }),
]

export default eslintConfig

next/core-web-vitals 更新 eslint-plugin-next 以对影响 Core Web Vitals 的许多规则进行错误处理，这些规则在默认情况下是警告。

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

与 TypeScript 一起使用​

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

eslint.config.mjs
import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname 在 Node.js v20.11.0 之后可用
  baseDirectory: import.meta.dirname,
})

const eslintConfig = [
  ...compat.config({
    extends: ['next/core-web-vitals', 'next/typescript'],
  }),
]

export default eslintConfig

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

与 Prettier 一起使用​

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

首先，安装依赖项：

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

eslint.config.mjs
import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname 在 Node.js v20.11.0 之后可用
  baseDirectory: import.meta.dirname,
})

const eslintConfig = [
  ...compat.config({
    extends: ['next', 'prettier'],
  }),
]

export default eslintConfig

对暂存文件运行 lint​

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

.lintstagedrc.js
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],
}

在生产构建期间禁用 lint​

如果你不希望 ESLint 在 next build 期间运行，可以在 next.config.js 中将 eslint.ignoreDuringBuilds 选项设置为 true：

next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  eslint: {
    // 警告：这允许生产构建成功完成，即使
    // 你的项目有 ESLint 错误。
    ignoreDuringBuilds: true,
  },
}

export default nextConfig

迁移现有配置​

如果你已经在应用程序中配置了 ESLint，我们建议直接从此插件扩展，而不是包含 eslint-config-next，除非满足几个条件。

推荐的插件规则集​

如果以下条件为真：

  • 你已经安装了一个或多个以下插件（单独或通过不同的配置，如 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：

Terminal
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，确保它在其他配置之后最后扩展。例如：

eslint.config.mjs
import js from '@eslint/js'
import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname 在 Node.js v20.11.0 之后可用
  baseDirectory: import.meta.dirname,
  recommendedConfig: js.configs.recommended,
})

const eslintConfig = [
  ...compat.config({
    extends: ['eslint:recommended', 'next'],
  }),
]

export default eslintConfig

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

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

最后于 更新