ESLint 到 Oxlint 渐进式迁移快速上手指南

前言

最近（2025 年 8 月 22 日），Oxlint 发布了新版本，已支持 Type-aware 模式，并提供了一个便捷的迁移工具，可以将 ESLint 配置自动迁移到 Oxlint。

如果你正在为 ESLint 的性能问题和模糊的错误提示困扰，现在正是迁移到 Oxlint 的最佳时机。

本文将手把手带你从 ESLint 迁移到 Oxlint，可选择完全弃用 ESLint 或两者共存（这也是官方文档推荐的模式）。

（Type-aware 解释：启用 Type-aware 模式后，Oxlint 会基于 TypeScript 的类型信息来分析和检查你的代码，而不仅仅是基于静态的 JavaScript 语法规则。）

Oxlint 最直观的优势

• 性能极佳：Oxlint 使用 Rust 编写。
  • 在我的测试中，对我的主题仓库进行同样的 Lint 检查，ESLint 需要 2.5 秒，Oxlint 仅需 33 毫秒（不开启 Type-aware），475 毫秒（开启 Type-aware）。
• 提示更友好：与 ESLint 仅提示错误所在行和触发规则不同，Oxlint 会详细说明错误的原因、具体位置（使用多种颜色进行解释）、以及如何解决。

迁移步骤

首先，确保你的 ESLint 已经在使用平面配置文件（Flat config，通常为 eslint.config.js）。如果你仍在使用 .eslintrc.js 和 eslintrc.json。请参考这篇配置迁移指南将其迁移至平面配置指南。

安装依赖

在项目中添加 oxlint 和 oxlint-tsgolint（当你需要 type-aware 规则支持时）：

pnpm add -D oxlint@latest oxlint-tsgolint@latest

pnpm add -D oxlint@latest oxlint-tsgolint@latest

npm install -D oxlint@latest oxlint-tsgolint@latest

npm install -D oxlint@latest

yarn add -D oxlint@latest oxlint-tsgolint@latest

yarn add -D oxlint@latest

bun add -D oxlint@latest oxlint-tsgolint@latest

bun add -D oxlint@latest

注：由于 Oxlint 是使用 Rust 编写，因此它并不依赖于 Node.js 运行。你可以直接前往发布页下载二进制文件并运行，或者使用以下命令运行：

pnpm dlx oxlint@latest

npx oxlint@latest

yarn dlx oxlint@latest

bunx oxlint@latest

deno run npm:oxlint@latest

自动迁移 ESLint 配置

Oxlint 官方提供了一个迁移工具，可以将 ESLint Flat Config 配置转换为 Oxlint 配置。

执行：

pnpm dlx @oxlint/migrate --type-aware

参数解释：

• --type-aware：启用 TypeScript 类型感知

更多参数请参照官方说明文档。

pnpm dlx @oxlint/migrate

npx @oxlint/migrate --type-aware

npx @oxlint/migrate

yarn dlx @oxlint/migrate --type-aware

yarn dlx @oxlint/migrate

bunx @oxlint/migrate

deno run npm:@oxlint/migrate

运行后，工具会在项目根目录生成 .oxlint.json 配置文件，并将 ESLint 规则尽可能映射到 Oxlint 规则。

如果迁移过程中没有提示 unsupported rule，说明你在 ESLint 中使用的规则已被覆盖，基本可以直接移除 ESLint。

如果提示 unsupported rule, but in development，你可以尝试启用 Nursery 规则集（开发中规则集）。即在原本的指令后添加 --with-nursery 参数去添加对这些规则的支持：

pnpm dlx @oxlint/migrate --type-aware --with-nursery

移除 ESLint（可选）

如果在上一步未提示 unsupported rule ，即确认 Oxlint 配置完整覆盖 ESLint 规则，可以直接移除 ESLint：

# 卸载 ESLint 依赖
pnpm remove eslint @eslint/js typescript-eslint
# 如果有额外的 eslint 插件，比如 eslint-plugin-*
pnpm remove eslint-plugin-xxx eslint-config-xxx ...

最后删除 eslint.config.js、.eslintrc.* 文件。

在 package.json 中替换脚本

完全迁移到 Oxlint

请参照 Oxlint CLI 文档 将原本的 ESLint 命令替换为 Oxlint 指令，如：

{
  "scripts": {
    "lint": "eslint --fix ./src"
  }
}

替换为

{
  "scripts": {
    "lint": "oxlint --type-aware --fix ./src"
  }
}

lint-staged 配置更新

{
  "lint-staged": {
    "**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx,vue,astro,svelte}": "oxlint"
  }
}

与 ESLint 共存（渐进迁移）

如果不想一次性迁移，可以先让 Oxlint + ESLint 一起跑，如：

{
  "scripts": {
    "lint": "oxlint --type-aware --fix ./src && eslint --fix ./src"
  }
}

这样，你可以先使用 Oxlint 进行快速检查和提供详细提示，处理大部分规则，然后再让 ESLint 补充 Oxlint 尚不支持的部分。

接着使用 eslint-plugin-oxlint 在 eslint 中禁用 oxlint 已经支持的规则，避免重复检查：

pnpm add -D eslint-plugin-oxlint@latest

npm install -D eslint-plugin-oxlint@latest

yarn add -D eslint-plugin-oxlint@latest

bun add -D eslint-plugin-oxlint@latest

最后在 eslint.config.js 中进行配置：

import oxlint from 'eslint-plugin-oxlint';

export default [
  ...// 其他插件
  ...oxlint.buildFromOxlintConfigFile('./.oxlintrc.json'), // oxlint 应该为最后一个插件
];

其他

如果你使用了注释来忽略某些检查，Oxlint 同样支持这种方式，具体配置可参考相关文档。

结语

欢迎在评论区留言交流，祝你生活愉快。