ESLint Flat Config 遷移最後期限：2026 必讀指南

如果你的專案還在使用 .eslintrc 的配置格式，現在是時候認真考慮遷移了。ESLint 10 將在 2026 年正式發布，而 Flat Config（扁平配置）是 ESLint 未來唯一的方向。傳統的 .eslintrc 格式已經在 ESLint 9 被標記為 deprecated，2026 年的某個時間點將是實質上的最後遷移期限。這個升級的遷移成本比以往任何一次都高，特別是如果你有複雜的 ESLint 配置或依賴很多 plugins。

為什麼要關心 ESLint 的這次升級

ESLint 的配置格式從 2013 年到現在幾乎沒有變化過。多數前端工程師對 .eslintrc 的格式已經非常熟悉，各種 preset 和 plugin 的文檔都以 .eslintrc 格式為基礎。

但 ESLint 9 引入的 Flat Config，徹底改變了配置的結構和語法。這不只是「换个写法」——很多現有的 ESLint plugins 和 configurations 需要更新才能支援 Flat Config。

如果你等到 ESLint 11 或 12 才開始遷移，可能會遇到「需要的 plugin 已經不維護了」的問題。現在遷移，是最從容的時機。

Flat Config 的基本語法

從 .eslintrc 到 eslint.config.js

過去的 .eslintrc.json：

{
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended"
  ],
  "plugins": ["@typescript-eslint"],
  "rules": {
    "@typescript-eslint/no-unused-vars": "error"
  },
  "parser": "@typescript-eslint/parser",
  "env": {
    "browser": true,
    "es2021": true
  }
}

現在的 eslint.config.js：

// eslint.config.js
import js from '@eslint/js';
import tseslint from 'typescript-eslint';

export default [
  // 使用內建的 recommended 配置
  js.configs.recommended,

  // 使用 TypeScript ESLint 的 recommended 配置
  ...tseslint.configs.recommended,

  // 自定義規則
  {
    rules: {
      'no-unused-vars': 'off',
      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
    },
  },

  // 設定檔案範圍
  {
    files: ['**/*.test.ts'],
    rules: {
      '@typescript-eslint/no-explicit-any': 'off',
    },
  },
];

Flat Config 的核心差異

1. 從 JSON 到 JavaScript

Flat Config 使用 JavaScript 檔案（.js 或 .mjs），而不是 JSON：

// ✅ Flat Config 可以使用變數和條件邏輯
const isCI = process.env.CI === 'true';

export default [
  {
    rules: {
      // CI 環境下更嚴格
      'no-console': isCI ? 'error' : 'warn',
    },
  },
];

// ❌ .eslintrc 無法使用動態值
{
  "rules": {
    "no-console": "warn"
  }
}

2. 擴展方式從 extends 到 Array

// Flat Config：使用 array 组合配置
export default [
  js.configs.recommended,
  ...tseslint.configs.recommended,
  prettier.configs.recommended,  // 加入 Prettier
];

3. Plugin 引入方式改變

// ❌ 過去
{
  "plugins": ["react", "@typescript-eslint"],
  "extends": ["plugin:react/recommended"]
}

// ✅ 現在：直接 import
import react from 'eslint-plugin-react';
import tseslint from 'typescript-eslint';

export default [
  // plugins 現在是直接使用的對象
  {
    plugins: {
      react,
      '@typescript-eslint': tseslint,
    },
    rules: {
      'react/no-unknown-property': 'error',
    },
  },
];

4. 語法規則微調

// ❌ 過去的格式
"quotes": ["error", "single"]

// ✅  Flat Config：保持相同
{
  rules: {
    'quotes': ['error', 'single'],
  },
}

多數規則的格式在 Flat Config 裡沒有變化，但需注意某些規則的選項可能有細微差異。

官方遷移工具

@eslint/migrate-config

ESLint 提供了官方的遷移工具：

# 安裝
npm install -g @eslint/migrate-config

# 執行遷移
npx @eslint/migrate-config .eslintrc.json
# 或
eslint --migrate-config .eslintrc.json

這個工具會：

讀取你的 .eslintrc.json
轉換為 eslint.config.js 格式
輸出到你的終端讓你確認

遷移步驟

# 步驟 1：確保 ESLint 是最新版
npm install -D eslint@latest

# 步驟 2：安裝遷移工具
npm install -D @eslint/migrate-config

# 步驟 3：執行遷移
npx @eslint/migrate-config .eslintrc.json

# 步驟 4：驗證
npx eslint .

# 步驟 5：如果有錯誤，檢查輸出並修復

遷移後需要手動調整的部分

遷移工具無法處理的部分，需要手動調整：

// 1. 自定義 parser 設定
// ❌ 過去
{
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": 2021,
    "sourceType": "module"
  }
}

// ✅ 現在
import tseslint from 'typescript-eslint';

export default [
  ...tseslint.configs.recommended,
  {
    languageOptions: {
      parser: tseslint.parser,
      parserOptions: {
        ecmaVersion: 2021,
        sourceType: 'module',
      },
    },
  },
];

// 2. Glob patterns 設定
export default [
  {
    files: ['**/*.ts', '**/*.tsx'],
    rules: {
      '@typescript-eslint/no-unused-vars': 'error',
    },
  },
];

與 Prettier 的整合

過去的衝突

ESLint 和 Prettier 過去的整合比較麻煩，需要用 eslint-config-prettier 來關閉與 Prettier 衝突的 ESLint 規則。

// ✅ 現在
import prettier from 'eslint-plugin-prettier';
import prettierConfig from 'eslint-config-prettier';

export default [
  ...tseslint.configs.recommended,
  prettierConfig,  // 直接加入
  {
    plugins: { prettier },
    rules: {
      'prettier/prettier': 'error',
    },
  },
];

適合 Flat Config 的場景

Flat Config 特別適合

Monorepo：可以為每個 package 定義不同的配置
多框架專案：同時有 React 和 Vue 的專案，可以分開配置
需要動態配置：根據環境變數調整規則

// Monorepo 範例
import { defineConfig } from 'eslint(defineConfig)';

export default defineConfig([
  // 共享配置
  {
    files: ['**/*.ts'],
    rules: { '@typescript-eslint/no-unused-vars': 'error' },
  },

  // React 專用配置
  {
    files: ['apps/web/**/*.tsx'],
    plugins: { react },
    rules: { 'react/no-unknown-property': 'error' },
  },
]);

結語：現在是遷移的最佳時機

ESLint Flat Config 的遷移，有點像當年從 Babel 6 到 Babel 7 的升級——遲早要做，早做比晚做從容。

Flat Config 的設計更符合現代 JavaScript 的開發方式：使用 ESM語法、支援動態配置、更好地整合 TypeScript。對於新專案，Flat Config 沒有額外的學習成本——你本來就應該從一開始就用 Flat Config。

對於現有專案，現在的遷移成本是最低的：官方遷移工具已經足夠成熟，主流 plugins 都支援 Flat Config，生態系正在往 Flat Config 方向發展。