本技能將引導您將 JavaScript/TypeScript 專案從 ESLint 遷移至 Oxlint。

概述

Oxlint 是一個高效能的 linter，以 Rust 原生實作了許多熱門的 ESLint 規則。它可以與 ESLint 並行使用，或作為完整的替代方案。

官方提供了遷移工具，本技能將使用它：@oxlint/migrate

步驟 1：執行自動遷移

在專案根目錄執行遷移工具：

npx @oxlint/migrate

這會讀取您的 ESLint 平面設定檔（例如 eslint.config.js）並從中產生 .oxlintrc.json 檔案。在大多數情況下，它會自動找到您的 ESLint 設定檔。

更多資訊請參閱下方選項。

主要選項

選項	說明
`--type-aware`	包含來自 `@typescript-eslint` 的型別感知規則（遷移後需要安裝 `oxlint-tsgolint` 套件）
`--with-nursery`	包含仍在開發中的實驗性規則，可能尚未完全穩定或與 ESLint 對應規則一致
`--js-plugins [bool]`	啟用/停用透過 `jsPlugins` 進行的 ESLint 外掛遷移（預設：啟用）
`--details`	列出無法遷移的規則
`--replace-eslint-comments`	將所有 `// eslint-disable` 註解轉換為 `// oxlint-disable`
`--output-file <file>`	指定不同的輸出路徑（預設：`.oxlintrc.json`）

如果您的 ESLint 設定檔不在預設位置，請明確傳入路徑：

npx @oxlint/migrate ./path/to/eslint.config.js

步驟 2：檢視產生的設定檔

遷移後，請檢視產生的 .oxlintrc.json。

外掛對應

遷移工具會自動將 ESLint 外掛對應至 oxlint 內建的對應項目。以下表格供您在檢視產生的設定檔時參考：

ESLint 外掛	Oxlint 外掛名稱
`@typescript-eslint/eslint-plugin`	`typescript`
`eslint-plugin-react` / `eslint-plugin-react-hooks`	`react`
`eslint-plugin-import` / `eslint-plugin-import-x`	`import`
`eslint-plugin-unicorn`	`unicorn`
`eslint-plugin-jsx-a11y` / `eslint-plugin-jsx-a11y-x`	`jsx-a11y`
`eslint-plugin-react-perf`	`react-perf`
`eslint-plugin-promise`	`promise`
`eslint-plugin-jest`	`jest`
`@vitest/eslint-plugin`	`vitest`
`eslint-plugin-jsdoc`	`jsdoc`
`eslint-plugin-next`	`nextjs`
`eslint-plugin-node`	`node`
`eslint-plugin-vue`	`vue`

預設外掛（當省略 plugins 欄位時啟用）：unicorn、typescript、oxc。
明確設定 plugins 陣列會覆蓋這些預設值。

ESLint 核心規則在 oxlint 中可直接使用，無需在設定檔中設定外掛。

規則類別

Oxlint 將規則分組為類別，以便進行批量設定，但預設僅啟用 correctness：

{
  "categories": {
    "correctness": "error",
    "suspicious": "warn"
  }
}

可用的類別：correctness（預設：啟用）、suspicious、pedantic、perf、style、restriction、nursery。

rules 中的個別規則設定會覆蓋類別設定。

@oxlint/migrate 會關閉 correctness，以避免啟用 ESLint 設定中未啟用的額外規則。您可以在遷移後視需要啟用其他類別。

檢查未遷移的規則

使用 --details 執行以查看哪些 ESLint 規則無法遷移：

npx @oxlint/migrate --details

檢視輸出結果，並決定是否要為這些規則保留 ESLint。某些規則可能會在 --details 的輸出中被提及，表示 oxlint 中有對應的規則但未被遷移工具自動對應。在這種情況下，請考慮在遷移後手動啟用對應的 oxlint 規則。

步驟 3：安裝 Oxlint

安裝核心 oxlint 套件（根據您的套件管理員使用 yarn install、pnpm install、vp install、bun install 等）：

npm install -D oxlint

如果您打算使用需要 TypeScript 型別資訊的型別感知規則，並希望安裝 oxlint-tsgolint 套件：

npm install -D oxlint-tsgolint

預設情況下，除了上述套件外，不需要其他套件，但您需要保留/安裝任何已遷移至 jsPlugins 的額外 ESLint 外掛。請勿將 @oxlint/migrate 加入 package.json，它僅供一次性使用。

步驟 4：處理不支援的功能

某些功能需要手動處理：

本地外掛（相對路徑匯入）：必須手動遷移至 jsPlugins
eslint-plugin-prettier：支援，但速度非常慢。建議改用 oxfmt，或將 prettier --check 作為獨立步驟與 oxlint 並行使用。
覆蓋設定中的 settings：Oxlint 不支援在 overrides 區塊內使用 settings。
ESLint v9+ 外掛：並非所有外掛都能與 oxlint 的 JS Plugins API 相容，但大多數可以。

本地外掛

如果您在專案儲存庫中有自訂的 ESLint 規則，可以在執行遷移工具後手動將其遷移至 .oxlintrc.json 的 jsPlugins 欄位：

{
  "jsPlugins": ["./path/to/my-plugin.js"],
  "rules": {
    "local-plugin/rule-name": "error"
  }
}

外部 ESLint 外掛

對於沒有內建 oxlint 對應項目的 ESLint 外掛，請使用 jsPlugins 欄位載入它們：

{
  "jsPlugins": ["eslint-plugin-custom"],
  "rules": {
    "custom/my-rule": "warn"
  }
}

步驟 5：更新 CI 與腳本

將 ESLint 指令取代為 oxlint。路徑引數為選填；oxlint 預設使用目前工作目錄。

# 之前
npx eslint src/
npx eslint --fix src/

# 之後
npx oxlint src/
npx oxlint --fix src/

常見 CLI 選項

ESLint	oxlint 對應項目
`eslint .`	`oxlint`（預設：檢查目前工作目錄）
`eslint src/`	`oxlint src/`
`eslint --fix`	`oxlint --fix`
`eslint --max-warnings 0`	`oxlint --deny-warnings` 或 `--max-warnings 0`
`eslint --format json`	`oxlint --format json`

其他 oxlint 選項：

--tsconfig <path>：指定 tsconfig.json 路徑，除非您的 tsconfig.json 名稱非標準，否則可能不需要。

提示

如有需要，您可以與 ESLint 並行執行：Oxlint 設計為在遷移期間與 ESLint 互補，但透過 JS Plugins，許多專案可以在不遺失太多規則的情況下完全切換。
停用註解可正常運作：oxlint 支援 // eslint-disable 和 // eslint-disable-next-line 註解。如有需要，可在執行 @oxlint/migrate 時使用 --replace-eslint-comments 將其轉換為 // oxlint-disable 對應項目。
列出可用規則：執行 npx oxlint --rules 查看所有支援的規則，或參閱規則文件。
Schema 支援：如果遷移工具未自動加入，請在 .oxlintrc.json 中加入 "$schema": "./node_modules/oxlint/configuration_schema.json" 以獲得編輯器自動完成功能。
輸出格式：default、stylish、json、github、gitlab、junit、checkstyle、unix
忽略檔案：如果您有 .eslintignore，oxlint 支援它，但建議將忽略模式移至 .oxlintrc.json 的 ignorePatterns 欄位，以保持一致性與簡潔性。所有透過 .gitignore 檔案忽略的檔案和路徑，oxlint 預設也會忽略。
如果您多次執行遷移工具，請在完成遷移後刪除由遷移工具建立的 .oxlintrc.json.bak 備份檔案。
如果您沒有使用任何 JS Plugins 且已取代 ESLint 設定，則可以從專案相依性中移除所有 ESLint 套件。
確保您的編輯器已設定為使用 oxlint 而非 ESLint 進行 lint 與錯誤回報。您可能想為偏好的編輯器安裝 Oxc 擴充功能。更多詳細資訊請參閱 https://oxc.rs/docs/guide/usage/linter/editors.html。

migrate-oxlint

相關技能

概述