从 ESLint 迁移

🌐 Migrate from ESLint

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

🌐 This guide is for existing JavaScript and TypeScript projects that currently use ESLint and want to migrate to Oxlint.

如果你正在启动一个新项目，或者不需要保留现有的 ESLint 配置，我们建议初始化一个全新的 Oxlint 配置：

🌐 If you are starting a new project, or do not need to preserve an existing ESLint configuration, we recommend initializing a fresh Oxlint config instead:

oxlint --init

概览

🌐 Overview

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

🌐 Oxlint and ESLint share similar configuration concepts, but they differ in supported rules and config formats.

Oxlint 已经支持来自 ESLint 核心和各种流行插件的 600 多条规则。我们计划支持几乎所有现有的 ESLint 核心规则，这项工作正在进行中。

🌐 Oxlint already supports more than 600 rules from ESLint core and various popular plugins. We intend to support nearly all existing ESLint core rules, and this work is ongoing.

迁移时，请注意以下事项：

🌐 When migrating, expect the following:

• 大多数 ESLint 核心规则和常用插件规则都受到支持
• 某些规则可能尚不可用
• ESLint 配置文件必须转换为 Oxlint 的配置格式
• Oxlint 旨在逐步采用；不需要事先进行全面迁移
• Oxlint 的 JS 插件允许使用 Oxlint 未原生实现的 ESLint 插件

从 ESLint 扁平配置迁移

🌐 Migrating from an ESLint flat config

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

🌐 If your project uses an ESLint v9/v10 flat config (e.g. eslint.config.js or eslint.config.mjs), you can migrate automatically using @oxlint/migrate.

运行迁移工具

🌐 Run the migration tool

从项目根目录开始：

🌐 From the project root:

npx @oxlint/migrate <optional-eslint-flat-config-path>

这个命令：

🌐 This command:

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

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

🌐 The generated .oxlintrc.json config can be edited manually after migration.

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

查看可用选项列表以获取更多详细信息。

🌐 See the list of available options for more details.

类型感知的 TypeScript 规则

🌐 Type-Aware TypeScript rules

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

🌐 If your ESLint setup uses typescript-eslint with type-aware rules, you can pass the --type-aware flag:

npx @oxlint/migrate --type-aware

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

🌐 This ensures the generated Oxlint config includes type-aware rules.

请注意，类型感知的代码检查需要 oxlint-tsgolint，并且基于 TypeScript 的原生重写（即 TypeScript 7），但在大多数 TypeScript 项目中应该可以在不进行太多升级工作的情况下采用。

🌐 Note that type-aware linting requires oxlint-tsgolint, and is based on the TypeScript native rewrite (aka TypeScript 7), but should be possible to adopt in most TypeScript projects without too much upgrade work.

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

🌐 For further information on Oxlint's type-aware support, see the Type-Aware Linting page.

JavaScript 插件

🌐 JavaScript plugins

如果你的 ESLint 配置使用了 Oxlint 不原生支持的插件，你可以通过 JavaScript 插件来保留它们。

🌐 If your ESLint config uses plugins that are not supported natively by Oxlint, you can retain them using JavaScript plugins.

要将 ESLint 插件与原生支持的插件一起迁移，请使用 --js-plugins 标志：

🌐 To migrate ESLint plugins along with the natively-supported plugins, use the --js-plugins flag:

npx @oxlint/migrate --js-plugins

这允许你通过 Oxlint 继续使用那些规则，同时配合原生的规则/插件。JS 插件功能并不支持所有 ESLint 插件，但 Oxlint 的 JavaScript 插件系统涵盖了 ESLint v9 API 的大部分内容，并且正在不断改进。大多数处理 JavaScript/TypeScript 代码的 ESLint 插件在 Oxlint 中应该都能正常工作。

🌐 This allows you to continue using those rules via Oxlint alongside the native rules/plugins. The JS Plugins functionality does not support all ESLint plugins, but Oxlint's JavaScript plugin system covers a vast majority of the ESLint v9 API and is actively being improved. Most ESLint plugins covering JavaScript/TypeScript code should work in Oxlint without problems.

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

🌐 For more information on JavaScript Plugins, see the JS Plugins page.

本地自定义 ESLint 插件

🌐 Local custom ESLint plugins

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

🌐 If you use local custom ESLint plugins from within your own repo (e.g. import pluginMyCompany from './eslint-plugin-my-company/lib/index.js'), these will not be migrated automatically by @oxlint/migrate right now.

但是，它们可以在运行迁移脚本后手动添加到 .oxlintrc.json 中：

🌐 However, they can be added manually to the .oxlintrc.json after running the migration script:

.oxlintrc.json

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

同时运行 Oxlint 和 ESLint

🌐 Running Oxlint and ESLint together

如果 Oxlint 中没有提供所有必需的规则，你可以同时运行 Oxlint 和 ESLint。

🌐 If not all required rules are available in Oxlint, you can run Oxlint and ESLint side by side.

一种常见的设置是：

🌐 A common setup is:

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

由于 Oxlint 的速度明显快于 ESLint，建议先运行 Oxlint 以便及早发现错误，然后仅在必要时再使用 ESLint。

🌐 Because Oxlint is significantly faster than ESLint, it is recommended to run Oxlint first to catch errors early, then fall back to ESLint only if needed.

例如：

🌐 For example:

oxlint && eslint

在 ESLint 中禁用重叠规则

🌐 Disabling overlapping rules in ESLint

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

🌐 You can use eslint-plugin-oxlint to disable ESLint rules that are already handled by Oxlint:

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

这可以减少重复的诊断，显著缩短你的代码检查时间，并允许 ESLint 只专注于 Oxlint 尚未支持的规则。

🌐 This reduces duplicate diagnostics, can help cut down your linting time considerably, and allows ESLint to focus only on rules that Oxlint does not yet support.

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

🌐 Long-term - once remaining important rules have been added in Oxlint - we strongly recommend moving fully to Oxlint to simplify your setup and reduce the number of dependencies for your project.

从旧版ESLint（v8.x）配置迁移

🌐 Migrating from legacy ESLint (v8.x) configs

如果你的项目使用带有遗留配置文件（例如 .eslintrc.js 或 .eslintrc.json）的 ESLint v8.x，它们无法通过 @oxlint/migrate 自动迁移。

🌐 If your project uses ESLint v8.x with legacy config files (such as .eslintrc.js or .eslintrc.json), they cannot be migrated automatically by @oxlint/migrate.

在某些情况下，你可以先使用 @eslint/migrate-config 将它们自动迁移到 ESLint 扁平配置，然后再使用 @oxlint/migrate 迁移到 Oxlint。

🌐 In some cases, you can migrate them automatically to an ESLint flat config with @eslint/migrate-config first, and then to Oxlint using @oxlint/migrate.

“传统”的 ESLint v8.x 配置文件结构与 Oxlint 的配置格式非常相似，因此对于简单的设置，大多数规则和选项可以直接转换。

🌐 The "legacy" ESLint v8.x configuration file shape maps closely to Oxlint’s config format, so for simple setups most rules and options can be translated directly.

规则/插件支持

🌐 Rule/plugin support

你可能在 ESLint 中依赖一些特定规则，而这些规则尚未移植到 Oxlint。

🌐 You may have specific rules that you rely on in ESLint that are not yet ported to Oxlint.

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

🌐 Almost all rules from our supported plugins will be ported - and a majority already have been. For those that will not be ported, some rules are deprecated in the original plugins, or have alternatives implemented already.

你可以查看 meta issue 来了解规则/插件的实现状态，以确认你依赖的规则是否计划实现，或者是否已经被其他等效规则实现。

🌐 You can check the meta issue for rule/plugin implementation status to see if the rules you rely on are planned for implementation, or if they have already been implemented by other, equivalent rules.

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

🌐 For plugins that are not implemented natively in Oxlint, it is recommended to use JS Plugins.