oxlint

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Oxlint — High-Performance JS/TS Linter

Oxlint — 高性能JS/TS代码检查工具

Oxlint is 50-100x faster than ESLint. It ships with 690+ rules covering ESLint core, TypeScript, React, Jest, Unicorn, jsx-a11y, and more. It prioritizes high-signal correctness checks by default — things that are incorrect, unsafe, or useless — so teams can adopt it without drowning in false positives.

Oxlint的速度比ESLint快50-100倍。它内置690+条规则，涵盖ESLint核心、TypeScript、React、Jest、Unicorn、jsx-a11y等内容。默认情况下，它优先进行高信号的正确性检查——即检查错误、不安全或无用的代码——因此团队采用它时不会被大量误报困扰。

Detection

检测

Before linting, confirm the project uses oxlint by checking for any of:

```
oxlint
```
in
```
package.json
```
devDependencies/dependencies
An
```
.oxlintrc.json
```
file in the project root
An
```
oxlint.config.ts
```
file in the project root
An
```
oxlint
```
or
```
lint
```
script in
```
package.json
```
that references
```
oxlint
```

If none of these exist, the project doesn't use oxlint — don't run it.

在进行代码检查前，通过以下任一方式确认项目是否使用oxlint：

```
package.json
```
的devDependencies/dependencies中存在
```
oxlint
```
项目根目录下存在
```
.oxlintrc.json
```
文件
项目根目录下存在
```
oxlint.config.ts
```
文件
```
package.json
```
中的
```
oxlint
```
或
```
lint
```
脚本引用了
```
oxlint
```

如果以上都不存在，则该项目未使用oxlint——请勿运行它。

Running Oxlint

运行Oxlint

After code changes

代码修改后

Run oxlint to check your work. Prefer the project's npm script if one exists:

bash

undefined

运行oxlint检查你的代码。如果项目有对应的npm脚本，优先使用：

bash

undefined

If package.json has a lint script using oxlint

若package.json中有使用oxlint的lint脚本

npm run lint

Otherwise, run directly

否则直接运行

npx oxlint

undefined

npx oxlint

undefined

Fixing issues automatically

自动修复问题

bash

npx oxlint --fix

Use

--fix

for safe automatic fixes. Avoid

--fix-dangerously

unless the user explicitly asks for it — it can apply unsafe transformations.

bash

npx oxlint --fix

使用

--fix

进行安全的自动修复。除非用户明确要求，否则避免使用

--fix-dangerously

——它会应用不安全的代码转换。

Linting specific files

检查特定文件

After editing only a few files, you can lint just those:

bash

npx oxlint src/components/Button.tsx src/utils/helpers.ts

当仅修改了少量文件时，你可以只检查这些文件：

bash

npx oxlint src/components/Button.tsx src/utils/helpers.ts

Interpreting output

解读输出结果

Oxlint prints diagnostics with rule names in parentheses, e.g.

(no-unused-vars)

. When fixing:

Read the diagnostic message carefully — oxlint gives precise, actionable information
Fix the underlying code issue rather than suppressing the rule
Only add
```
// oxlint-ignore
```
comments as a last resort when the diagnostic is a genuine false positive

Oxlint会输出带有规则名称（括号内）的诊断信息，例如

(no-unused-vars)

。修复时：

仔细阅读诊断信息——oxlint会提供精准、可操作的内容
修复代码的根本问题，而非禁用规则
只有当诊断信息确实是误报时，才作为最后手段添加
```
// oxlint-ignore
```
注释

Output formats

输出格式

For CI or tooling integration:

bash

npx oxlint --format json        # Machine-readable JSON
npx oxlint --format github      # GitHub Actions annotations
npx oxlint --format unix        # Simple one-line-per-error format

用于CI或工具集成：

bash

npx oxlint --format json        # 机器可读的JSON格式
npx oxlint --format github      # GitHub Actions注释格式
npx oxlint --format unix        # 每行一个错误的简单格式

Configuration

配置

Creating a config

创建配置文件

bash

npx oxlint --init

This generates an

.oxlintrc.json

starter config.

bash

npx oxlint --init

这会生成一个

.oxlintrc.json

初始配置文件。

Config file format (.oxlintrc.json)

配置文件格式（.oxlintrc.json）

The config uses JSONC (JSON with comments). Key sections:

jsonc

{
  // Enable/disable individual rules with severity levels
  "rules": {
    "no-unused-vars": "error",
    "no-console": "warn",
    "no-plusplus": ["error", { "allowForLoopAfterthoughts": true }]
  },

  // Enable groups of related rules by category
  "categories": {
    "correctness": "error",   // Definitely-wrong code
    "suspicious": "warn",     // Probably-wrong code
    "pedantic": "off",        // Opinionated style checks
    "perf": "warn",           // Performance anti-patterns
    "style": "off",           // Cosmetic preferences
    "restriction": "off",     // Extra-strict rules (opt-in)
    "nursery": "off"          // Unstable/experimental rules
  },

  // Plugins to enable (setting this overwrites defaults, so list all you want)
  "plugins": ["typescript", "unicorn", "oxc"],

  // File-specific overrides
  "overrides": [
    {
      "files": ["**/*.test.{ts,tsx}"],
      "rules": { "no-console": "off" }
    },
    {
      "files": ["scripts/**"],
      "rules": { "no-console": "off" }
    }
  ],

  // Environment globals
  "env": {
    "browser": true,
    "node": true
  },

  // Plugin-wide settings
  "settings": {
    "react": {
      "linkComponents": [{ "name": "Link", "linkAttribute": "to" }]
    },
    "jsx-a11y": {
      "components": { "Link": "a", "Button": "button" }
    }
  },

  // Type-aware linting (requires tsconfig)
  "options": {
    "typeAware": true
  }
}

配置文件使用JSONC（带注释的JSON）格式。关键部分如下：

jsonc

{
  // 启用/禁用单个规则并设置严重级别
  "rules": {
    "no-unused-vars": "error",
    "no-console": "warn",
    "no-plusplus": ["error", { "allowForLoopAfterthoughts": true }]
  },

  // 按类别启用相关规则组
  "categories": {
    "correctness": "error",   // 绝对错误的代码
    "suspicious": "warn",     // 可能错误的代码
    "pedantic": "off",        // 主观的风格检查
    "perf": "warn",           // 性能反模式
    "style": "off",           // 美观偏好
    "restriction": "off",     // 额外严格的规则（需手动启用）
    "nursery": "off"          // 不稳定/实验性规则
  },

  // 要启用的插件（设置此项会覆盖默认值，因此需列出所有需要的插件）
  "plugins": ["typescript", "unicorn", "oxc"],

  // 针对特定文件的覆盖配置
  "overrides": [
    {
      "files": ["**/*.test.{ts,tsx}"],
      "rules": { "no-console": "off" }
    },
    {
      "files": ["scripts/**"],
      "rules": { "no-console": "off" }
    }
  ],

  // 环境全局变量
  "env": {
    "browser": true,
    "node": true
  },

  // 插件全局设置
  "settings": {
    "react": {
      "linkComponents": [{ "name": "Link", "linkAttribute": "to" }]
    },
    "jsx-a11y": {
      "components": { "Link": "a", "Button": "button" }
    }
  },

  // 类型感知检查（需要tsconfig）
  "options": {
    "typeAware": true
  }
}

Rule severity levels

规则严重级别

```
"off"
```
/
```
"allow"
```
— Disable the rule
```
"warn"
```
— Report but don't fail the build
```
"error"
```
/
```
"deny"
```
— Report and exit non-zero

Unique rule names can omit plugin prefix:

"no-console"

"eslint/no-console"

```
"off"
```
/
```
"allow"
```
— 禁用规则
```
"warn"
```
— 报告问题但不导致构建失败
```
"error"
```
/
```
"deny"
```
— 报告问题并返回非零退出码

唯一的规则名称可以省略插件前缀：

"no-console"

"eslint/no-console"

。

规则类别

Categories group rules by intent. The recommended starting point:

```
correctness: "error"
```
— Always on. Catches real bugs.
```
suspicious: "warn"
```
— Good signal, occasionally noisy.
Everything else: enable incrementally as the team is ready.

类别按规则的意图分组。推荐的初始设置：

```
correctness: "error"
```
— 始终启用，捕获真实的bug。
```
suspicious: "warn"
```
— 信号良好，偶尔会有噪声。
其他类别：随着团队准备就绪逐步启用。

Available plugins

可用插件

Enabled by default:

typescript

unicorn

oxc

Opt-in (CLI flags or config):

Plugin	CLI flag	Purpose
react	`--react-plugin`	React-specific rules
jsx-a11y	`--jsx-a11y-plugin`	Accessibility rules for JSX
nextjs	`--nextjs-plugin`	Next.js best practices
import	`--import-plugin`	Import/export validation
jest	`--jest-plugin`	Jest testing rules
vitest	`--vitest-plugin`	Vitest testing rules
jsdoc	`--jsdoc-plugin`	JSDoc documentation rules
node	`--node-plugin`	Node.js-specific rules
promise	`--promise-plugin`	Promise best practices
react-perf	`--react-perf-plugin`	React performance rules
vue	`--vue-plugin`	Vue.js rules

To disable a default plugin:

--disable-typescript-plugin

--disable-unicorn-plugin

--disable-oxc-plugin

默认启用：

typescript

unicorn

oxc

需手动启用（通过CLI标志或配置文件）：

插件	CLI标志	用途
react	`--react-plugin`	React专属规则
jsx-a11y	`--jsx-a11y-plugin`	JSX可访问性规则
nextjs	`--nextjs-plugin`	Next.js最佳实践
import	`--import-plugin`	导入/导出验证
jest	`--jest-plugin`	Jest测试规则
vitest	`--vitest-plugin`	Vitest测试规则
jsdoc	`--jsdoc-plugin`	JSDoc文档规则
node	`--node-plugin`	Node.js专属规则
promise	`--promise-plugin`	Promise最佳实践
react-perf	`--react-perf-plugin`	React性能规则
vue	`--vue-plugin`	Vue.js规则

要禁用默认插件：

--disable-typescript-plugin

--disable-unicorn-plugin

--disable-oxc-plugin

。

Extending shared configs

扩展共享配置

jsonc

{
  "extends": ["./configs/base.json", "./configs/frontend.json"]
}

Later entries override earlier ones. Paths resolve relative to the declaring config.

jsonc

{
  "extends": ["./configs/base.json", "./configs/frontend.json"]
}

后续配置会覆盖之前的配置。路径相对于当前配置文件解析。

Monorepo support

单仓库多项目支持

Oxlint supports nested configs. Each directory can have its own

.oxlintrc.json

that overrides parent settings. Disable with

--disable-nested-config

if unwanted.

Oxlint支持嵌套配置。每个目录都可以有自己的

.oxlintrc.json

文件，覆盖父级设置。如果不需要此功能，可使用

--disable-nested-config

禁用。

CLI Quick Reference

CLI快速参考

Flag	What it does
`-c, --config=PATH`	Use a specific config file
`--tsconfig=PATH`	TypeScript config for path aliases
`--fix`	Auto-fix safe issues
`--fix-suggestions`	Also apply suggested fixes
`-A, --allow=RULE`	Suppress a rule (e.g., `-A no-console` )
`-W, --warn=RULE`	Warn on a rule
`-D, --deny=RULE`	Error on a rule
`--quiet`	Suppress warnings, show only errors
`--deny-warnings`	Treat warnings as errors (exit non-zero)
`--max-warnings=N`	Fail if more than N warnings
`-f, --format=FMT`	Output format: default, json, github, unix, etc.
`--ignore-pattern=PAT`	Exclude files matching pattern
`--type-aware`	Enable type-informed rules (needs tsconfig)
`--print-config`	Show resolved config (useful for debugging)
`--rules`	List all available rules

Categories can also be used with

-A

-W

-D

bash

npx oxlint -D correctness -W suspicious -A pedantic

标志	功能
`-c, --config=PATH`	使用指定的配置文件
`--tsconfig=PATH`	用于路径别名的TypeScript配置
`--fix`	自动修复安全的问题
`--fix-suggestions`	同时应用建议的修复方案
`-A, --allow=RULE`	禁用某条规则（例如： `-A no-console` ）
`-W, --warn=RULE`	将某条规则设为警告级别
`-D, --deny=RULE`	将某条规则设为错误级别
`--quiet`	抑制警告，仅显示错误
`--deny-warnings`	将警告视为错误（返回非零退出码）
`--max-warnings=N`	如果警告数量超过N则构建失败
`-f, --format=FMT`	输出格式：默认、json、github、unix等
`--ignore-pattern=PAT`	排除匹配指定模式的文件
`--type-aware`	启用类型感知规则（需要tsconfig）
`--print-config`	显示解析后的配置（用于调试）
`--rules`	列出所有可用规则

类别也可以与

-A

-W

-D

一起使用：

bash

npx oxlint -D correctness -W suspicious -A pedantic

Suppressing rules inline

内联禁用规则

// oxlint-ignore no-console -- needed for debug logging
console.log(debugInfo);

// oxlint-ignore-next-line no-unused-vars
const _placeholder = computeValue();

Use

oxlint-ignore

(not

eslint-disable

) — oxlint recognizes both, but prefer its native syntax.

// oxlint-ignore no-console -- 用于调试日志
console.log(debugInfo);

// oxlint-ignore-next-line no-unused-vars
const _placeholder = computeValue();

使用

oxlint-ignore

（而非

eslint-disable

）——oxlint可以识别这两种语法，但推荐使用它的原生语法。

Migrating from ESLint

从ESLint迁移

If the project is moving from ESLint to oxlint:

Side-by-side approach — Run both linters, with
```
eslint-plugin-oxlint
```
disabling rules that oxlint already covers:
bash
```
npm install -D eslint-plugin-oxlint
```
Add it as the last plugin in your ESLint config.
Full replacement — Use
```
@oxlint/migrate
```
to convert your ESLint config:
bash
```
npx @oxlint/migrate
```
This generates an
```
.oxlintrc.json
```
from your existing ESLint configuration.

如果项目要从ESLint迁移到oxlint：

并行方式 — 同时运行两个代码检查工具，使用
```
eslint-plugin-oxlint
```
禁用oxlint已覆盖的规则：
bash
```
npm install -D eslint-plugin-oxlint
```
在ESLint配置中将它作为最后一个插件添加。
完全替换 — 使用
```
@oxlint/migrate
```
转换你的ESLint配置：
bash
```
npx @oxlint/migrate
```
这会从现有的ESLint配置生成一个
```
.oxlintrc.json
```
文件。

Supported file types

支持的文件类型

.js

.mjs

.cjs

.ts

.mts

.cts

.jsx

.tsx

.vue

.svelte

.astro

For

.vue

.svelte

, and

.astro

files, oxlint lints only the

<script>

blocks.

.js

.mjs

.cjs

.ts

.mts

.cts

.jsx

.tsx

.vue

.svelte

.astro

对于

.vue

、

.svelte

和

.astro

文件，oxlint仅检查

<script>

块中的代码。