ESLint

從版本 11.0.0 起，Next.js 提供一個開箱即可使用的 ESLint。新增 next lint 作為一個指令檔到 package.json：

"scripts": {
  "lint": "next lint"
}

接著，執行 npm run lint 或 yarn lint

yarn lint

如果你尚未將 ESLint 配置到你的應用程式，你將會被指導整個安裝和配置的流程。

yarn lint

# 你可能會看到如下的對話框:
#
# ? How would you like to configure ESLint?
#
# ❯   Base configuration + Core Web Vitals rule-set (recommended)
#     Base configuration
#     None

可以選擇以下三個選項的其中之一：

  • Strict: 包含基本的 ESLint 配置和一個更嚴格的網站體驗核心指標規則集。這是針對開發人員首次設定 ESLint 的推薦配置。

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

  • Base: 包含 Next.js 基本 ESLint 配置。

    {
  "extends": "next"
}

  • Cancel:不包含任何 ESLint 配置。僅當你想要自行設定 ESLint 配置時才選擇此選項。

如果選擇了兩個配置中的其中一個， Next.js 將會自動地安裝 eslint 和 eslint-config-next 作為應用程式內的開發相依並且會在專案的根目錄中建立一個包含所選配置的 .eslintrc.json 檔案。

你可以在任何時候呼叫 next lint 執行 ESLint 來捕捉錯誤。一旦設置了 ESLint，它也會在每次建構期間自動執行（next build）。錯誤會導致建構失敗，但警告不會。

如果你不想要在 next build 期間執行 ESLint，可以參考這份文件 忽略 ESLint。

我們建議使用更適切的 整合 在你開發期間透過編輯器來查看警告和錯誤訊息。

ESLint 配置

預設的設定（eslint-config-next）已經包括了所有在 Next.js 中獲得最佳體驗及你所需的一切。如果您的應用程式中尚未配置 ESLint，我們建議使用 next lint 來設定 ESLint 以及此配置。

如果你想使用 eslint-config-next 和其他 ESLint 配置，請參考額外的配置來學習如何使用而不導致任何的衝突。

以下的 ESLint 插件的推薦規則集也都在 eslint-config-next 使用：

這將優先來自 next.config.js 的配置。

ESLint 插件

Next.js 提供 ESLint 插件，eslint-plugin-next，已經打包在基本的配置中來捕捉 Next.js 應用程式中的一般的問題：

  • ✔: Enabled in the recommended configuration
RuleDescription
✔️@next/next/google-font-displayEnforce font-display behavior with Google Fonts.
✔️@next/next/google-font-preconnectEnsure preconnect is used with Google Fonts.
✔️@next/next/inline-script-idEnforce id attribute on next/script components with inline content.
✔️@next/next/next-script-for-gaPrefer next/script component when using the inline script for Google Analytics.
✔️@next/next/no-assign-module-variablePrevent assignment to the module variable.
✔️@next/next/no-before-interactive-script-outside-documentPrevent usage of next/script's beforeInteractive strategy outside of pages/_document.js.
✔️@next/next/no-css-tagsPrevent manual stylesheet tags.
✔️@next/next/no-document-import-in-pagePrevent importing next/document outside of pages/_document.js.
✔️@next/next/no-duplicate-headPrevent duplicate usage of <Head> in pages/_document.js.
✔️@next/next/no-head-elementPrevent usage of <head> element.
✔️@next/next/no-head-import-in-documentPrevent usage of next/head in pages/_document.js.
✔️@next/next/no-html-link-for-pagesPrevent usage of <a> elements to navigate to internal Next.js pages.
✔️@next/next/no-img-elementPrevent usage of <img> element to prevent layout shift.
✔️@next/next/no-page-custom-fontPrevent page-only custom fonts.
✔️@next/next/no-script-component-in-headPrevent usage of next/script in next/head component.
✔️@next/next/no-styled-jsx-in-documentPrevent usage of styled-jsx in pages/_document.js.
✔️@next/next/no-sync-scriptsPrevent synchronous scripts.
✔️@next/next/no-title-in-document-headPrevent usage of <title> with Head component from next/document.
✔️@next/next/no-typosPrevent common typos in Next.js's data fetching functions
✔️@next/next/no-unwanted-polyfillioPrevent duplicate polyfills from Polyfill.io.

如果你的應用程式中已經具備 ESLint 的配置，我們建議你從這個插件擴充而不是僅僅包含 eslint-config-next，除非某些條件被滿足了。請參考推薦的插件規則集來學習更多。

自定義設定

rootDir

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

如果 Next.js 專案是未安裝在根目錄下 (例如：monorepo) 且使用了 eslint-plugin-next，你可以在 .eslintrc 透過 setting 屬性告訴 eslint-plugin-next 哪裡可以找到你的 Next.js 專案。

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

rootDir can be a path (relative or absolute), a glob (i.e. "packages/*/"), or an array of paths and/or globs. rootDir 可以是一個路徑 (相對或絕對)，一個 glob (例如："package/*/")，或是一個路徑和(或) globs 的陣列。

整理自定義的目錄和檔案

By default, Next.js will run ESLint for all files in the pages/, components/, lib/, and src/ directories. However, you can specify which directories using the dirs option in the eslint config in next.config.js for production builds:

預設之下，Next.js 將會為在 pages/、components/、lib/ 和 src/ 目錄下的所有檔案執行 ESLint。然而，你可以正式環境建構時在 next.config.js 中的 eslint 使用 dirs 選項來指定目錄。

module.exports = {
  eslint: {
    dirs: ['pages', 'utils'], // 只有在正式環境建構時在 'pages' 和 'utils' 執行 ESLint (next build)
  },
}

相同地，--dir 和 --file 標籤可用於 next lint 來針對特定目錄和檔案進行整理：

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

暫存

To improve performance, information of files processed by ESLint are cached by default. This is stored in .next/cache or in your defined build directory. If you include any ESLint rules that depend on more than the contents of a single source file and need to disable the cache, use the --no-cache flag with next lint. 為了最佳化效能，ESLint 處理的檔案訊息預設是暫存的。這個是儲存在 .next/cache 內或者在你定義的build directory

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

網站體驗核心指標

next/core-web-vitals 規則集會在第一次執行 next lint 時以及選擇嚴格選項時啟用。

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

如果會影響網站體驗核心指標的狀況之下，next/core-web-vitals 的預設會基於一些規則更新 eslint-plugin-next 的錯誤

next/core-web-vitals 入口點將會自動地被包含在使用 Create Next App 建構的新應用程式內。

其他工具的使用範例

Prettier

ESLint 也包含程式碼格式規則，這可能會與你既有的 Prettier 設定有所衝突。我們推薦包含 eslint-config-prettier 在你的 ESLint 配置中來確保兩者的正常運作。

首先， 安裝相依：

npm install --save-dev eslint-config-prettier
# or
yarn add --dev eslint-config-prettier

接著，增加 prettier 到你既有的 ESLint 配置中：

{
  "extends": ["next", "prettier"]
}

lint-staged

如果你想要使用 next/lint 和 lint-staged 在暫存的 git 檔案上執行 linter，你將需要在專案的根目錄下，新增以下所列出到你的 .lintstagerc.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],
}

遷移既有的配置

Recommended Plugin Ruleset 推薦的插件規則集

如果你已經在你的應用程式中配置了 ESLint 並且滿足以下任一條件：

  • 已經安裝了以下一個或多個插件（單獨安裝或透過不同的配置，例如 airbnb 或 react-app）：
    • react
    • react-hooks
    • jsx-a11y
    • import
  • 你已經定義與 Next.js 中的 Babel 配置方式不同的 parserOptions (我們不推薦這個作法，除非你已經自定義你的 Babel 配置)。
  • 你已經安裝 eslint-plugin-import 並定義處理導入的 Node.js 和 / 或 TypeScript resolvers

如果你比較喜歡這些已經在 eslint-config-next 配置好的屬性，我們建議你刪除這些設定或者是直接從 Next.js ESLint 插件擴充：

module.exports = {
  extends: [
    //...
    'plugin:@next/next/recommended',
  ],
}

插件一般來說可以在不需要執行 next lint 被安裝到專案中：

npm install --save-dev @next/eslint-plugin-next
# or
yarn add --dev @next/eslint-plugin-next

此消除了基於跨多種配置導入相同的插件或解析而可能產生的衝突或錯誤的風險。

額外配置

如果你已經單獨使用一個獨立的 ESLint 配置，且希望納入 eslint-config-next，請確保它是在其他配置後的最後一項擴充，例如：

{
  "extends": ["eslint:recommended", "next"]
}

next 配置已經為 parser、plugins 和 setting 處理了預設值的設定。除非您的狀況需要不同的配置，否則不需要手動重新聲明它們的屬性。如果你納入任何可分享的配置，你需要確保這些屬性不會被覆寫或修改。否則，我們建議你移除任何與 next 共享行為的配置或如上述所言，從既有的 Next.js ESLint 插件做擴充。

本篇文章由AndreaFan123

AndreaFan123

貢獻翻譯。瞭解如何參與貢獻