oxlint

Oxlint — 高性能 JS/TS Linter

Oxlint 的速度比 ESLint 快 50–100 倍。它提供 690 多条规则，涵盖 ESLint 核心、TypeScript、React、Jest、Unicorn、jsx-a11y 等。默认优先检查高价值的正确性问题——错误、不安全或无用的代码——因此团队可以采用它，而不必被误报淹没。

检测

运行 lint 前，先检查以下任一项，确认项目正在使用 oxlint：

• package.json 的 devDependencies/dependencies 中包含 oxlint
• 项目根目录中有 .oxlintrc.json 文件
• 项目根目录中有 oxlint.config.ts 文件
• package.json 中的 oxlint 或 lint 脚本引用了 oxlint

如果以上都不存在，则项目没有使用 oxlint——不要运行它。

运行 Oxlint

修改代码后

运行 oxlint 检查你的工作。若项目提供了 npm 脚本，优先使用：

# If package.json has a lint script using oxlint
npm run lint

# Otherwise, run directly
npx oxlint

自动修复问题

npx oxlint --fix

使用 --fix 进行安全的自动修复。除非用户明确要求，否则避免使用 --fix-dangerously——它可能会应用不安全的转换。

检查特定文件

只修改了少数文件后，可以只检查这些文件：

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

解读输出

Oxlint 会输出诊断信息，并在括号中显示规则名称，例如 (no-unused-vars)。修复时：

1. 仔细阅读诊断信息——oxlint 会提供准确且可执行的信息
2. 修复代码中的根本问题，而不是屏蔽规则
3. 只有在诊断确实属于误报时，才将 // oxlint-ignore 注释作为最后手段

输出格式

用于 CI 或工具集成：

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

配置

创建配置

npx oxlint --init

这会生成一个 .oxlintrc.json 起始配置。

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

配置使用 JSONC（带注释的 JSON）。主要部分：

{
  // 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
  }
}

规则严重级别

• "off" / "allow" — 禁用规则
• "warn" — 报告问题，但不会导致构建失败
• "error" / "deny" — 报告问题并以非零状态码退出

唯一的规则名称可以省略插件前缀："no-console" = "eslint/no-console"。

类别

类别按照规则的意图对其进行分组。推荐的起点：

• correctness: "error" — 始终启用。可捕获实际错误。
• suspicious: "warn" — 信号质量较高，但偶尔会产生噪声。
• 其他所有类别：根据团队准备情况逐步启用。

可用插件

默认启用： 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。

扩展共享配置

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

后面的条目会覆盖前面的条目。路径相对于声明该配置的文件解析。

Monorepo 支持

Oxlint 支持嵌套配置。每个目录都可以有自己的 .oxlintrc.json，用于覆盖父级设置。如果不需要，可通过 --disable-nested-config 禁用。

CLI 快速参考

标志	作用
-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	输出格式：default、json、github、unix 等
--ignore-pattern=PAT	排除与模式匹配的文件
--type-aware	启用类型感知规则（需要 tsconfig）
--print-config	显示解析后的配置（便于调试）
--rules	列出所有可用规则

也可以在 -A/-W/-D 中使用类别：

npx oxlint -D correctness -W suspicious -A pedantic

在代码中禁用规则

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

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

使用 oxlint-ignore（而不是 eslint-disable）——oxlint 能识别两者，但建议使用其原生语法。

从 ESLint 迁移

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

1. 并行使用 — 同时运行两个代码检查器，并使用 eslint-plugin-oxlint 禁用 oxlint 已覆盖的规则：

   npm install -D eslint-plugin-oxlint
   

   将其作为 ESLint 配置中的最后一个插件添加。

2. 完全替换 — 使用 @oxlint/migrate 转换 ESLint 配置：

   npx @oxlint/migrate
   

   这会根据现有的 ESLint 配置生成 .oxlintrc.json。

支持的文件类型

.js、.mjs、.cjs、.ts、.mts、.cts、.jsx、.tsx、.vue、.svelte、.astro

对于 .vue、.svelte 和 .astro 文件，oxlint 仅检查 <script> 块。