ESLint迁移到Oxlint完整指南：JavaScript/TypeScript项目性能优化工具

migrate-oxlint by oxc-project/oxc

1,000 周安装量

20,300 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/oxc-project/oxc --skill migrate-oxlint

开发自动化性能优化

🇨🇳中文介绍

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

概述

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

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

步骤 1：运行自动化迁移

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

npx @oxlint/migrate

该工具会读取您的 ESLint 扁平配置（例如 eslint.config.js）并从中生成一个 .oxlintrc.json 文件。在大多数情况下，它会自动找到您的 ESLint 配置文件。

更多信息请参见下面的选项。

关键选项

选项	描述
`--type-aware`

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

步骤 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`	`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。输出中可能会提到某些规则在 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 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 默认使用当前工作目录。

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

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

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

🇺🇸English

This skill guides you through migrating a JavaScript/TypeScript project from ESLint to Oxlint.

Overview

Oxlint is a high-performance linter that implements many popular ESLint rules natively in Rust. It can be used alongside ESLint or as a full replacement.

An official migration tool is available, and will be used by this skill: @oxlint/migrate

Step 1: Run Automated Migration

Run the migration tool in the project root:

npx @oxlint/migrate

This reads your ESLint flat config (eslint.config.js for example) and generates a .oxlintrc.json file from it. It will find your ESLint config file automatically in most cases.

See options below for more info.

Key Options

Option	Description
`--type-aware`	Include type-aware rules from `@typescript-eslint` (will require the `oxlint-tsgolint` package to be installed after migrating)
`--with-nursery`	Include experimental rules still under development, may not be fully stable or consistent with ESLint equivalents
`--js-plugins [bool]`	Enable/disable ESLint plugin migration via `jsPlugins` (default: enabled)
`--details`	List rules that could not be migrated
`--replace-eslint-comments`	Convert all `// eslint-disable` comments to `// oxlint-disable`
`--output-file <file>`	Specify a different output path (default: `.oxlintrc.json`)

If your ESLint config is not at the default location, pass the path explicitly:

npx @oxlint/migrate ./path/to/eslint.config.js

Step 2: Review Generated Config

After migration, review the generated .oxlintrc.json.

Plugin Mapping

The migration tool automatically maps ESLint plugins to oxlint's built-in equivalents. The following table is for reference when reviewing the generated config:

ESLint Plugin	Oxlint Plugin Name
`@typescript-eslint/eslint-plugin`	`typescript`
`eslint-plugin-react` / `eslint-plugin-react-hooks`	`react`
`eslint-plugin-import` / `eslint-plugin-import-x`	`import`

Default plugins (enabled when plugins field is omitted): unicorn, typescript, oxc. Setting the plugins array explicitly overrides these defaults.

ESLint core rules are usable in oxlint without needing to configure a plugin in the config file.

Rule Categories

Oxlint groups rules into categories for bulk configuration, though only correctness is enabled by default:

{
  "categories": {
    "correctness": "error",
    "suspicious": "warn"
  }
}

Available categories: correctness (default: enabled), suspicious, pedantic, perf, style, restriction, nursery.

Individual rule settings in rules override category settings.

@oxlint/migrate will turn correctness off to avoid enabling additional rules that weren't enabled by your ESLint config. You can choose to enable additional categories after migration if desired.

Check Unmigrated Rules

Run with --details to see which ESLint rules could not be migrated:

npx @oxlint/migrate --details

Review the output and decide whether to keep ESLint for those rules or not. Some rules may be mentioned in the output from --details as having equivalents in oxlint that were not automatically mapped by the migration tool. In those cases, consider enabling the equivalent oxlint rule manually after migration.

Step 3: Install Oxlint

Install the core oxlint package (use yarn install, pnpm install, vp install, bun install, etc. depending on your package manager):

npm install -D oxlint

If you want to add the oxlint-tsgolint package, if you intend to use type-aware rules that require TypeScript type information:

npm install -D oxlint-tsgolint

No other packages besides the above are needed by default, though you will need to keep/install any additional ESLint plugins that were migrated into jsPlugins. Do not add @oxlint/migrate to the package.json, it is meant for one-off usage.

Step 4: Handle Unsupported Features

Some features require manual attention:

Local plugins (relative path imports): Must be migrated manually to jsPlugins
eslint-plugin-prettier: Supported, but very slow. It is recommended to use oxfmt instead, or switch to prettier --check as a separate step alongside oxlint.
settings in override configs: Oxlint does not support settings inside overrides blocks.
ESLint v9+ plugins: Not all work with oxlint's JS Plugins API, but the majority will.

Local Plugins

If you have any custom ESLint rules in the project repo itself, you can migrate them manually after running the migration tool by adding them to the jsPlugins field in .oxlintrc.json:

{
  "jsPlugins": ["./path/to/my-plugin.js"],
  "rules": {
    "local-plugin/rule-name": "error"
  }
}

External ESLint Plugins

For ESLint plugins without a built-in oxlint equivalent, use the jsPlugins field to load them:

{
  "jsPlugins": ["eslint-plugin-custom"],
  "rules": {
    "custom/my-rule": "warn"
  }
}

Step 5: Update CI and Scripts

Replace ESLint commands with oxlint. Path arguments are optional; oxlint defaults to the current working directory.

# Before
npx eslint src/
npx eslint --fix src/

# After
npx oxlint src/
npx oxlint --fix src/

Common CLI Options

ESLint	oxlint equivalent
`eslint .`	`oxlint` (default: lints the cwd)
`eslint src/`	`oxlint src/`
`eslint --fix`	`oxlint --fix`
`eslint --max-warnings 0`	`oxlint --deny-warnings` or

Additional oxlint options:

--tsconfig <path>: Specify tsconfig.json path, likely unnecessary unless you have a non-standard name for tsconfig.json.

Tips

You can run alongside ESLint if necessary: Oxlint is designed to complement ESLint during migration, but with JS Plugins many projects can switch over fully without losing many rules.
Disable comments work: // eslint-disable and // eslint-disable-next-line comments are supported by oxlint. Use --replace-eslint-comments when running @oxlint/migrate to convert them to // oxlint-disable equivalents if desired.
List available rules: Run npx oxlint --rules to see all supported rules, or refer to the rule documentation.
Schema support: Add "$schema": "./node_modules/oxlint/configuration_schema.json" to .oxlintrc.json for editor autocompletion if the migration tool didn't do it automatically.
Output formats: default, , , , , , ,

References

Weekly Installs

1.0K

Repository

oxc-project/oxc

GitHub Stars

20.3K

First Seen

Mar 5, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

codex1.0K

github-copilot1.0K

opencode1.0K

cursor1.0K

kimi-cli1.0K

gemini-cli1.0K

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

102,200 周安装

Ignore files: .eslintignore is supported by oxlint if you have it, but it's recommended to move any ignore patterns into the ignorePatterns field in .oxlintrc.json for consistency and simplicity. All files and paths ignored via a .gitignore file will be ignored by oxlint by default as well.

If you ran the migration tool multiple times, remove the .oxlintrc.json.bak backup file created by the migration tool once you've finished migrating.

If you are not using any JS Plugins and have replaced your ESLint configuration, you can remove all ESLint packages from your project dependencies.

Ensure your editor is configured to use oxlint instead of ESLint for linting and error reporting. You may want to install the Oxc extension for your preferred editor. See https://oxc.rs/docs/guide/usage/linter/editors.html for more details.