migrate-oxlint

本技能指导您将 JavaScript/TypeScript 项目从 ESLint 迁移到 Oxlint。

概述

Oxlint 是一个高性能的 linter，它用 Rust 原生实现了许多流行的 ESLint 规则。它可以与 ESLint 一起使用，也可以完全替代 ESLint。

官方提供了一个迁移工具，本技能将使用它：@oxlint/migrate

步骤 1：运行自动迁移

在项目根目录运行迁移工具：

npx @oxlint/migrate

这将读取您的 ESLint 扁平配置（例如 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。

插件映射

迁移工具会自动将 ESLint 插件映射到 oxlint 的内置等效插件。以下表格供审查生成的配置时参考：

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

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

检查未迁移的规则

使用 --details 运行以查看哪些 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 并行的独立步骤。
• 覆盖配置中的 settings：Oxlint 不支持在 overrides 块内使用 settings。
• ESLint v9+ 插件：并非所有插件都能与 oxlint 的 JS 插件 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 默认使用当前工作目录。

# 之前
npx eslint src/
npx eslint --fix src/

# 之后
npx oxlint src/
npx oxlint --fix src/

常用 CLI 选项

ESLint	oxlint 等效选项
eslint .	oxlint（默认：检查当前工作目录）
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 名称非标准，否则可能不需要。

提示

• 如有必要，您可以与 ESLint 并行运行：Oxlint 旨在迁移期间补充 ESLint，但通过 JS 插件，许多项目可以完全切换而不会丢失太多规则。
• 禁用注释有效：oxlint 支持 // eslint-disable 和 // eslint-disable-next-line 注释。如果需要，可以在运行 @oxlint/migrate 时使用 --replace-eslint-comments 将它们转换为 // oxlint-disable 等效注释。
• 列出可用规则：运行 npx oxlint --rules 查看所有支持的规则，或参考规则文档。
• Schema 支持：如果迁移工具没有自动添加，可以将 "$schema": "./node_modules/oxlint/configuration_schema.json" 添加到 .oxlintrc.json 中，以获得编辑器自动补全。
• 输出格式：default、stylish、json、github、gitlab、junit、checkstyle、unix
• 忽略文件：如果您有 .eslintignore，oxlint 支持它，但建议将忽略模式移到 .oxlintrc.json 的 ignorePatterns 字段中，以保持一致性和简单性。通过 .gitignore 文件忽略的所有文件和路径默认也会被 oxlint 忽略。
• 如果您多次运行迁移工具，请在完成迁移后删除由迁移工具创建的 .oxlintrc.json.bak 备份文件。
• 如果您没有使用任何 JS 插件并且已经替换了 ESLint 配置，可以从项目依赖中删除所有 ESLint 包。
• 确保您的编辑器配置为使用 oxlint 而不是 ESLint 进行 lint 和错误报告。您可能希望为您喜欢的编辑器安装 Oxc 扩展。更多详情请参见 https://oxc.rs/docs/guide/usage/linter/editors.html。

参考

• CLI 参考
• 配置文件参考
• 完整的 Oxlint 规则列表和文档