Oxc

从 ESLint 迁移 ​

本指南适用于当前使用 ESLint 并希望迁移到 Oxlint 的现有 JavaScript 和 TypeScript 项目。

概述 ​

Oxlint 和 ESLint 共享相似的配置概念，但在支持的规则和配置格式上有所不同。

Oxlint 已经支持来自 ESLint 核心和各种流行插件的 700 多条规则。我们打算支持几乎所有现有的 ESLint 核心规则，这项工作正在进行中。请查看兼容性矩阵以验证对您的框架和文件类型的支持。

迁移时，请预期以下情况：

  • 大多数 ESLint 核心规则和流行插件规则已受支持
  • 某些规则可能尚不可用
  • ESLint 配置文件必须转换为 Oxlint 的配置格式
  • Oxlint 设计用于增量采用；不需要预先进行完整迁移
  • Oxlint 的 JS 插件允许使用 Oxlint 原生未实现的 ESLint 插件

使用 Skills 迁移 ​

您可以使用 migrate-oxlint 技能交互式迁移：

bash
npx skills add https://github.com/oxc-project/oxc --skill migrate-oxlint

安装后，运行 /migrate-oxlint，代理将引导您完成完整的迁移。

从 ESLint flat config 迁移 ​

如果您的项目使用 ESLint v9/v10 flat config（例如 eslint.config.js 或 eslint.config.mjs），您可以使用 @oxlint/migrate 自动迁移。

运行迁移工具 ​

从项目根目录：

bash
npx @oxlint/migrate <可选的-eslint-flat-config-路径>

此命令：

  • 读取您的 ESLint flat config 文件
  • 将支持的规则转换为 Oxlint 配置
  • 保留规则严重程度和选项
  • 保留文件和路径特定的覆盖，以允许仓库的不同部分使用不同的规则集
  • 将 globals（例如 ...globals.browser）转换为等效的 env 和 globals 值
  • 保留根 ignore 模式以忽略特定路径/文件

生成的 .oxlintrc.json 配置可以在迁移后手动编辑。

.eslintignore 文件将被 Oxlint 遵循，可以在迁移期间保留，但我们建议在迁移后将内容移到 .oxlintrc.json 中的 "ignorePatterns" 字段。通过仓库的 .gitignore 文件忽略的文件/路径也将被 Oxlint 自动遵循。

有关更多详细信息，请参阅可用选项列表。

类型感知 TypeScript 规则 ​

如果您的 ESLint 设置使用带有类型感知规则的 typescript-eslint，您可以传递 --type-aware 标志：

bash
npx @oxlint/migrate --type-aware

这确保生成的 Oxlint 配置包含类型感知规则。

请注意，类型感知 lint 需要 oxlint-tsgolint，并且基于 TypeScript 原生重写（即 TypeScript 7），但在大多数 TypeScript 项目中应该可以采用，无需太多升级工作。

有关 Oxlint 类型感知支持的更多信息，请参阅类型感知检查页面。

JavaScript 插件 ​

如果您的 ESLint 配置使用 Oxlint 原生不支持的插件，您可以使用 JavaScript 插件保留它们。@oxlint/migrate 默认会为您迁移这些插件。

这允许您通过 Oxlint 继续使用这些规则以及原生规则/插件。JS 插件功能不支持所有 ESLint 插件，但 Oxlint 的 JavaScript 插件系统覆盖了 ESLint v9 API 的绝大部分，并且正在积极改进。大多数覆盖 JavaScript/TypeScript 代码的 ESLint 插件应该可以在 Oxlint 中正常工作。

如果您不想迁移 ESLint 插件以用作 JS 插件，可以传递 --js-plugins=false。

有关 JavaScript 插件的更多信息，请参阅 JS 插件页面。

本地自定义 ESLint 插件 ​

如果您使用来自自己仓库内的本地自定义 ESLint 插件（例如 import pluginMyCompany from './eslint-plugin-my-company/lib/index.js'），这些目前不会被 @oxlint/migrate 自动迁移。

但是，它们可以在运行迁移脚本后手动添加到 Oxlint 配置文件：

json
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "jsPlugins": ["./eslint-plugin-company/lib/index.js"]
}
ts
import { defineConfig } from "oxlint";

export default defineConfig({
  jsPlugins: ["./eslint-plugin-company/lib/index.js"],
});

同时运行 Oxlint 和 ESLint ​

如果并非所有需要的规则都在 Oxlint 中可用，您可以同时运行 Oxlint 和 ESLint。

常见的设置是：

  1. 对所有支持的规则启用 Oxlint
  2. 对不支持的规则保留 ESLint
  3. 在 ESLint 中禁用重叠的规则

由于 Oxlint 明显比 ESLint 快，建议先运行 Oxlint 以尽早发现错误，然后仅在需要时回退到 ESLint。

例如：

bash
oxlint && eslint

在 ESLint 中禁用重叠规则 ​

您可以使用 eslint-plugin-oxlint 禁用已由 Oxlint 处理的 ESLint 规则：

bash
npm install --save-dev eslint-plugin-oxlint

这减少了重复诊断，可以显著减少您的检查时间，并允许 ESLint 仅专注于 Oxlint 尚不支持的规则。

长期来看——一旦 Oxlint 中添加了剩余的重要规则——我们强烈建议完全迁移到 Oxlint，以简化设置并减少项目的依赖数量。

从旧版 ESLint (v8.x) 配置迁移 ​

如果您的项目使用 ESLint v8.x 和旧版配置文件（例如 .eslintrc.js 或 .eslintrc.json），它们无法被 @oxlint/migrate 自动迁移。

在某些情况下，您可以先使用 @eslint/migrate-config 自动迁移到 ESLint flat config，然后使用 @oxlint/migrate 迁移到 Oxlint。

"旧版" ESLint v8.x 配置文件形式与 Oxlint 的配置格式密切相关，因此对于简单设置，大多数规则和选项可以直接转换。

规则/插件支持 ​

您可能有在 ESLint 中依赖的特定规则尚未移植到 Oxlint。

我们支持的插件的几乎所有规则都会被移植——而且大多数已经移植。对于那些不会被移植的规则，某些规则在原始插件中已弃用，或已有替代实现。

您可以查看 meta issue 了解规则/插件实现状态，看看您依赖的规则是否计划实现，或是否已由其他等效规则实现。

对于 Oxlint 原生未实现的插件，建议使用 JS 插件。

© 2026 VoidZero Inc. and Oxc contributors.