Oxc

从 ESLint 迁移 ​

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

概述 ​

Oxlint 与 ESLint 具有相似的配置概念，但在支持的规则和配置格式方面存在差异。

Oxlint 已经支持来自 ESLint 核心及各种流行插件的超过 600 个规则。我们计划支持几乎所有的现有 ESLint 核心规则，此项工作仍在进行中。

在迁移过程中，请注意以下事项：

  • 大多数 ESLint 核心规则和流行插件规则均已被支持
  • 部分规则可能尚未可用
  • 必须将 ESLint 配置文件转换为 Oxlint 的配置格式
  • Oxlint 设计为逐步采用；无需一次性完成全部迁移
  • Oxlint 的 JS 插件允许使用未由 Oxlint 原生实现的 ESLint 插件

从 ESLint 平面配置迁移到 Oxlint ​

如果您的项目使用的是 ESLint v9/v10 的平面配置（例如 eslint.config.js 或 eslint.config.mjs），可以使用 @oxlint/migrate 工具自动完成迁移。

运行迁移工具 ​

从项目根目录执行：

bash
npx @oxlint/migrate <可选的 ESLint 平面配置路径>

该命令会：

  • 读取您的 ESLint 平面配置文件
  • 将受支持的规则转换为 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 配置包含类型感知规则。

请注意，类型感知的检查需要 oxlint-tsgolint，基于 TypeScript 原生重写（即 TypeScript 7），但大多数 TypeScript 项目应能相对轻松地进行采用，无需过多升级工作。

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

JavaScript 插件 ​

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

这使您可以在使用 Oxlint 原生规则/插件的同时，继续通过 JS 插件使用这些规则。虽然 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 不会自动迁移这些插件。

不过，您可以在运行迁移脚本后，手动将其添加到 .oxlintrc.json 中：

.oxlintrc.json
json
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "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）配置迁移到 Oxlint ​

如果您的项目使用的是 ESLint v8.x 的旧版配置文件（如 .eslintrc.js 或 .eslintrc.json），则无法通过 @oxlint/migrate 工具自动迁移。

在某些情况下，您可以先使用 @eslint/migrate-config 将其自动迁移到 ESLint 平面配置，然后再使用 @oxlint/migrate 进行迁移。

旧版 ESLint v8.x 的配置结构与 Oxlint 的配置格式非常接近，因此对于简单配置，大多数规则和选项可以直接转换。

规则/插件支持 ​

您可能依赖某些在 Oxlint 中尚未迁移的 ESLint 特定规则。

我们支持的插件中的几乎所有规则都将被迁移——且大部分已有实现。对于那些不会被迁移的规则，有些已在原始插件中被弃用，或已有替代实现。

您可以通过查看 元问题 了解规则/插件的实现状态，确认您所依赖的规则是否已规划实现，或是否已有其他等效规则实现。

对于未在 Oxlint 中原生实现的插件，推荐使用 JS 插件。

© 2026 VoidZero Inc. 及 Oxc 贡献者。