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 配置以及更嚴格的 核心網頁指標規則集。這是首次設定 ESLint 的開發者推薦的配置。

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

• 基本：僅包含 Next.js 的基本 ESLint 配置。

  {
    "extends": "next"
  }

• 取消：不包含任何 ESLint 配置。僅在您計劃設定自訂 ESLint 配置時選擇此選項。

如果選擇了前兩個配置選項之一，Next.js 會自動在您的應用程式中安裝 eslint 和 eslint-config-next 作為依賴項，並在專案根目錄建立包含所選配置的 .eslintrc.json 檔案。

現在您可以在需要執行 ESLint 檢查錯誤時隨時執行 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 可以是相對或絕對路徑、glob (例如 "packages/*/") 或路徑和/或 glob 的陣列。

檢查自訂目錄和檔案

預設情況下，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"
  }
}

核心網頁指標

當首次執行 next lint 並選擇 嚴格 選項時，會啟用 next/core-web-vitals 規則集。

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

next/core-web-vitals 會更新 eslint-plugin-next，將預設為警告的若干規則改為錯誤，如果這些規則影響 核心網頁指標。

對於使用 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
• 您定義了特定的 parserOptions 且與 Next.js 中的 Babel 配置不同（除非您已自訂 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

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 插件（如上所述）。