Skip to main content
目录

ESLint配置

默认配置（eslint-config-next）包括一切，以便在Next.js中获得一个最佳的开箱即用的linting体验。 如果您的应用程序尚未配置ESLint，我们建议使用next lint设置ESLint以及此配置。

如果您想要在其他ESLint配置中使用eslint-config-next，请参阅附加配置部分，了解如何在不引起冲突的情况下使用它。

以下ESLint插件的建议规则集已包含在eslint-config-next中：

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

ESLint插件​

Next.js提供了一个ESLint插件，eslint-plugin-next，已经在基本配置中捆绑在一起， 使得可以捕获Next.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防止对模块变量的赋值。
@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防止使用<img>元素，因为这会导致较慢的LCP和更高的带宽。
@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。

如果您已经在应用程序中配置了ESLint，请直接从此插件扩展，而不是包含eslint-config-next，除非满足一些条件。 有关详细信息，请参阅建议的插件规则集。

自定义设置​

rootDir​

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

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

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

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

默认情况下，Next.js将运行ESLint以处理pages/，app/，components/，lib/和src/目录中的所有文件。 但是，您可以在next.config.js中的eslint配置中使用dirs选项指定要使用的目录：

next.config.js

module.exports = {
  eslint: {
    dirs: ['pages', 'utils'], // 仅在生产构建（next build）期间在'pages'和'util'目录上运行ESLint
  },
}

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

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属性更改它们：

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

Core Web Vitals​

当第一次运行next lint并选择strict选项时，将启用next/core-web-vitals规则集。

.eslintrc.json
{
  "extends": "next/core-web-vitals"
}

next/core-web-vitals更新eslint-plugin-next， 使其在影响Core Web Vitals的一些规则上发生错误，默认情况下这些规则是警告。

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

与其他工具一起使用​

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

然后，在您现有的ESLint配置中添加prettier：

.eslintrc.json
{
  "extends": ["next", "prettier"]
}

lint-staged​

如果您希望使用lint-staged使next lint在git的暂存文件上运行， 您将不得不将以下内容添加到项目根目录中的.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],
}

迁移现有配置​

建议的插件规则集​

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

您已经单独安装了以下插件之一（或通过其他配置，例如airbnb或react-app）：

  • react
  • react-hooks
  • jsx-a11y
  • import

您定义了与Next.js中的Babel配置不同的parserOptions（除非您已自定义了Babel配置，否则不建议这样做） 您已在Node.js和/或TypeScript解析器中安装了eslint-plugin-import，并定义了处理导入的解析器 然后，我们建议删除这些设置，如果您喜欢这些属性在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，请确保它在其他配置之后最后扩展。 例如：

.eslintrc.json
{
  "extends": ["eslint:recommended", "next"]
}

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

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