migrate-oxlint

用途

migrate-oxlint 用于指导将 JavaScript/TypeScript 项目的 linter 从 ESLint 迁移到 Oxlint。Oxlint 是一个高性能 linter，用 Rust 原生实现了许多流行的 ESLint 规则，既可以与 ESLint 并存，也可以完全替代 ESLint。该技能会使用官方迁移工具 @oxlint/migrate 完成自动化迁移。

主要能力

自动读取 ESLint flat config（例如 eslint.config.js），并生成 .oxlintrc.json 配置文件。
自动将 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。
支持通过 --details 列出无法迁移的规则，便于人工评估。
支持将 // eslint-disable 注释转换为 // oxlint-disable。
支持通过 jsPlugins 加载没有内置等价物的外部 ESLint 插件以及本地插件。

使用方式

第 1 步：运行自动化迁移

在项目根目录运行：

npx @oxlint/migrate

该命令会读取 ESLint flat config（例如 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。

默认插件（省略 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 配置中未启用的额外规则。迁移后可根据需要选择启用其他类别。

检查未迁移规则：

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 并行使用。
override 配置中的 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 默认使用当前工作目录。

Before

npx eslint src/ npx eslint --fix src/

After

npx oxlint src/ npx oxlint --fix src/

常见 CLI 选项对照：

eslint . 对应 oxlint（默认：lint 当前工作目录）
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 名称非标准，否则可能不需要。

适用场景

需要将 JavaScript/TypeScript 项目的 linter 从 ESLint 迁移或切换到 Oxlint。
希望使用 Rust 实现的高性能 linter，同时保留大量 ESLint 规则。
希望在迁移期间让 Oxlint 与 ESLint 并存，逐步过渡。

限制与提示

本地插件、override 中的 settings、部分 ESLint v9+ 插件等需要手动处理。
eslint-plugin-prettier 虽受支持但非常慢，建议改用 oxfmt 或独立的 prettier --check。
如果多次运行迁移工具，迁移完成后请删除迁移工具创建的 .oxlintrc.json.bak 备份文件。
如果不使用任何 JS Plugins 并已替换 ESLint 配置，可以从项目依赖中移除所有 ESLint 包。
确保编辑器配置为使用 oxlint 而非 ESLint 进行 lint 和错误报告，可安装 Oxc 编辑器扩展，详见 https://oxc.rs/docs/guide/usage/linter/editors.html。
可运行 npx oxlint --rules 查看所有支持的规则，或参考规则文档。
可在 .oxlintrc.json 中添加 "$schema": "./node_modules/oxlint/configuration_schema.json" 以获得编辑器自动补全（如果迁移工具未自动添加）。
输出格式：default、stylish、json、github、gitlab、junit、checkstyle、unix。
忽略文件：oxlint 支持 .eslintignore，但建议将忽略模式移入 .oxlintrc.json 的 ignorePatterns 字段以保持一致和简单。通过 .gitignore 忽略的所有文件和路径默认也会被 oxlint 忽略。
参考：CLI Reference、Config File Reference、完整 Oxlint 规则列表与文档。