5 分钟上手 Oxlint：比 ESLint 快 50 倍的代码检查神器（实战教程）

你有没有遇到过这样的场景：运行 eslint ./src 后，看着终端里滚动的文件列表，等待几十秒甚至更久？项目越大，等待越长，严重拖慢开发节奏。

今天，我要介绍一个能彻底改变这种体验的工具 —— Oxlint。它不仅比 ESLint 快 50 倍以上，而且开箱即用，几乎零学习成本。

什么是代码检查？

在深入 Oxlint 之前，先来理解”代码检查”（Linting）是什么。

为什么需要 Linter？

代码检查工具能帮你发现代码中的问题：

// 这些问题你可能一眼看不出来
const name = 'test';
function getName() {
  return nam; // 拼写错误！应该是 name
}

if (x = 10) { // 应该是 === 而不是 =
  console.log('x is 10');
}

var unused = 'I am never used'; // 定义了但从未使用

代码检查工具可以：

• 发现错误：拼写错误、语法问题、逻辑陷阱
• 统一风格：保持团队代码风格一致
• 提升质量：避免常见的代码问题

ESLint 是什么？

ESLint 是 JavaScript 生态中最流行的代码检查工具，几乎所有前端项目都在用。但它的性能问题一直被诟病：

• 大型项目检查时间过长
• 插件加载消耗大量时间
• 内存占用较高

Oxlint 是什么？

Oxlint 是 OXC 项目的一部分，用 Rust 编写，专门用于替代 ESLint。它的特点：

• 极致速度：比 ESLint 快 50-100 倍
• 兼容性好：支持 ESLint 规则和配置格式
• 开箱即用：无需复杂配置，默认启用推荐规则
• 持续更新：正在快速追赶 ESLint 生态

安装 Oxlint

安装 Oxlint 非常简单，有多种方式可以选择。

方式一：全局安装

# 使用 npm
npm install -g oxlint

# 使用 yarn
yarn global add oxlint

# 使用 pnpm
pnpm add -g oxlint

安装后，你可以在任何目录使用 oxlint 命令。

方式二：项目内安装

# 作为开发依赖安装
npm install oxlint --save-dev

然后在 package.json 中添加脚本：

{
  "scripts": {
    "lint": "oxlint ./src"
  }
}

方式三：无需安装，直接使用

# 使用 npx 临时运行
npx oxlint ./src

这种方式适合快速体验，或者不想全局安装的场景。

第一次使用

安装完成后，让我们来实际体验一下。

检查单个文件

假设有一个文件 src/main.js：

// src/main.js
const unusedVar = 'I am not used';

function greeting(name) {
  console.log('Hello, ' + nam); // 拼写错误
  return 'Hello, ' + name;
}

greeting('World');

运行检查：

oxlint src/main.js

输出结果：

  ⚠ eslint(no-unused-vars): 'unusedVar' is defined but never used.
    ╭─[src/main.js:2:7]
  2 │   const unusedVar = 'I am not used';
    ·         ─────┬────
    ·              ╰── 'unusedVar' is defined here.
    ╰────────────────────────────────────

  ⚠ eslint(no-undef): 'nam' is not defined.
    ╭─[src/main.js:5:28]
  5 │     console.log('Hello, ' + nam);
    ·                            ─┬─
    ·                             ╰── 'nam' is not defined.
    ╰────────────────────────────────

  Finished in 3ms on 1 file with 0 errors and 2 warnings.

可以看到，Oxlint 发现了两个问题：

1. unusedVar 定义了但从未使用
2. nam 变量未定义（应该是 name）

检查整个项目

# 检查 src 目录下所有文件
oxlint ./src

# 检查多种文件类型
oxlint "./src/**/*.{js,jsx,ts,tsx,vue}"

输出格式：

  Finished in 12ms on 234 files with 0 errors and 5 warnings.

注意到了吗？12 毫秒检查 234 个文件！

自动修复问题

Oxlint 支持自动修复部分问题：

# 自动修复可修复的问题
oxlint ./src --fix

自动修复的内容包括：

• 移除未使用的变量
• 修复简单的代码风格问题
• 调整代码格式

实战：给现有项目添加 Oxlint

让我们完整演练一遍，给一个项目添加 Oxlint。

步骤一：创建测试项目

# 创建项目目录
mkdir my-project
cd my-project

# 初始化 npm
npm init -y

# 创建源码目录
mkdir src

创建测试文件 src/index.js：

// src/index.js
import React from 'react';

// 未使用的变量
const API_URL = 'https://api.example.com';
const unusedConfig = { debug: true };

// 函数定义
function fetchData(url) {
  // 缺少错误处理
  return fetch(url).then(res => res.json());
}

// 使用 var 而不是 const/let
var data = null;

// 主函数
async function main() {
  data = await fetchData(API_URL);
  console.log('Data loaded:', data);
}

main();

步骤二：安装 Oxlint

npm install oxlint --save-dev

步骤三：在 package.json 中添加脚本

{
  "name": "my-project",
  "scripts": {
    "lint": "oxlint ./src",
    "lint:fix": "oxlint ./src --fix"
  },
  "devDependencies": {
    "oxlint": "^0.15.0"
  }
}

步骤四：运行第一次检查

npm run lint

输出示例：

  ⚠ eslint(no-unused-vars): 'unusedConfig' is defined but never used.
    ╭─[src/index.js:8:7]
  8 │   const unusedConfig = { debug: true };
    ·         ───────┬──────
    ·                ╰── 'unusedConfig' is defined here.
    ╰───────────────────────────────────────

  ⚠ eslint(no-var): Unexpected var, use let or const instead.
    ╭─[src/index.js:17:3]
 17 │   var data = null;
    ·   ─────┬────
    ·        ╰── Use `let` or `const` instead of `var`.
    ╰───────────────────────────────────────

  Finished in 4ms on 1 file with 0 errors and 2 warnings.

步骤五：理解输出结果

Oxlint 的输出包含几个关键信息：

1. 规则名称：如 no-unused-vars、no-var
2. 问题位置：文件名、行号、列号
3. 问题描述：清晰说明问题所在
4. 统计信息：检查耗时、文件数量、错误和警告数

步骤六：自动修复问题

npm run lint:fix

修复后，src/index.js 的变化：

// src/index.js
import React from 'react';

// 未使用的变量被移除
const API_URL = 'https://api.example.com';

// 函数定义
function fetchData(url) {
  // 缺少错误处理
  return fetch(url).then(res => res.json());
}

// var 被改为 let
let data = null;

// 主函数
async function main() {
  data = await fetchData(API_URL);
  console.log('Data loaded:', data);
}

main();

配置文件入门

Oxlint 支持通过配置文件自定义规则。

创建配置文件

在项目根目录创建 oxlint.json：

{
  "rules": {
    "no-unused-vars": "error",
    "no-console": "warn",
    "no-var": "error",
    "prefer-const": "warn"
  }
}

规则级别

每个规则可以设置三种级别：

级别	说明
"off" 或 0	关闭规则
"warn" 或 1	警告，但不阻塞 CI
"error" 或 2	错误，会返回非零退出码

常用规则配置

{
  "rules": {
    // 变量相关
    "no-unused-vars": "error",
    "no-undef": "error",
    "prefer-const": "warn",

    // 代码风格
    "no-var": "error",
    "eqeqeq": ["error", "always"],
    "curly": ["warn", "multi-line"],

    // 最佳实践
    "no-console": "warn",
    "no-debugger": "error",
    "no-alert": "warn"
  }
}

忽略文件

创建 .oxlintignore 文件来排除不需要检查的目录：

# .oxlintignore
node_modules/
dist/
build/
*.min.js
*.d.ts

VS Code 集成

在编辑器中实时看到代码问题，能大大提高开发效率。

安装插件

1. 打开 VS Code
2. 搜索 “oxlint” 插件
3. 安装 Oxlint 插件

配置插件

在 .vscode/settings.json 中添加配置：

{
  "oxlint.enable": true,
  "oxlint.run": "onSave",
  "oxlint.configPath": "./oxlint.json"
}

效果展示

安装插件后，保存文件时会自动检查：

// 编辑器中直接显示波浪线提示
const unused = 'I am never used';  // ~~~~~~ 'unused' is defined but never used

var oldStyle = 'use let/const';    // ~~~ Use `let` or `const` instead of `var`.

鼠标悬停在波浪线上，可以看到详细的问题说明和修复建议。

常见问题解答

Oxlint 能完全替代 ESLint 吗？

目前还不能完全替代，但在大多数场景下已经够用。

Oxlint 的优势：

• 速度极快，适合日常开发
• 支持大部分常用规则
• 配置简单，开箱即用

当前的局限：

• 部分高级规则尚未实现
• 插件生态不如 ESLint 丰富
• 框架特定规则（如 vue-eslint-plugin）支持有限

如何从 ESLint 迁移？

渐进式迁移策略：

1. 并行运行：同时保留 ESLint 和 Oxlint

   {
     "scripts": {
       "lint": "oxlint ./src && eslint ./src"
     }
   }

2. 逐步切换：先用 Oxlint 处理日常开发，CI 中保留 ESLint

3. 完全迁移：当 Oxlint 满足所有需求后，移除 ESLint

Oxlint 和 ESLint 的检查结果不一样？

这是正常的，原因包括：

• 规则实现细节可能有差异
• 默认启用的规则集不同
• 部分规则尚未实现

解决方法：通过配置文件统一规则。

支持哪些文件类型？

Oxlint 支持：

• JavaScript (.js, .mjs, .cjs)
• TypeScript (.ts, .tsx, .mts, .cts)
• JSX (.jsx)
• Vue (.vue)
• Astro (.astro)
• Svelte (.svelte)

性能对比实测

让我们用真实数据说话。

测试环境

• 项目：一个中型前端项目
• 文件数量：约 500 个 .ts/.tsx 文件
• 机器：MacBook Pro M1，16GB 内存

测试结果

工具	首次运行时间	增量运行时间
ESLint	42 秒	38 秒
Oxlint	0.6 秒	0.4 秒

Oxlint 比 ESLint 快约 70 倍！

这意味着：

• Git pre-commit 钩子从分钟级降到秒级
• CI 流水线大幅缩短
• 开发反馈周期显著缩短

总结

本文介绍了 Oxlint 的核心用法：

内容	说明
安装	npm install -g oxlint 或 npx oxlint
检查文件	oxlint ./src
自动修复	oxlint ./src --fix
配置文件	oxlint.json 定义规则
编辑器集成	安装 VS Code Oxlint 插件

Oxlint 的核心价值：让代码检查从”等待”变成”即时完成”。

下一步

想了解更多 Oxlint 的高级配置和完整规则列表？访问 OXC 中文文档 - Oxlint 章节

下一篇文章，我们将学习 Oxfmt —— 让代码格式化也快起来！

---

💡 相关阅读：

• 上一篇：前端工具太慢？试试用 Rust 写的 OXC
• OXC 中文文档