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 檔案。

現在您可以隨時執行 next lint 來運行 ESLint 捕捉錯誤。設置完成後，ESLint 也會在每次建構 (next build) 時自動運行。錯誤會導致建構失敗，而警告則不會。

如果您不希望 ESLint 在 next build 時運行，請參閱 忽略 ESLint 的文件。

我們建議使用合適的 整合工具，在開發期間直接在程式碼編輯器中查看警告和錯誤。

ESLint 配置

預設配置 (eslint-config-next) 包含您在 Next.js 中獲得最佳開箱即用 linting 體驗所需的一切。如果您的應用程式尚未配置 ESLint，我們建議使用 next lint 來設置 ESLint 及此配置。

如果您想將 eslint-config-next 與其他 ESLint 配置一起使用，請參閱 附加配置 部分，了解如何避免衝突。

以下 ESLint 插件的推薦規則集均包含在 eslint-config-next 中：

• 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 入口點。

與其他工具一起使用

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
• 您定義了與 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：

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 插件進行擴展。