Oxc

配置 ​

Oxlint 无需额外配置即可直接使用，但大多数团队会提交一个配置文件（.oxlintrc.json 或 oxlint.config.ts），以确保本地运行、编辑器和 CI 之间的一致性。

本页重点介绍项目配置：规则、类别、插件、覆盖项和共享设置。

创建配置文件 ​

在当前目录生成初始配置（使用 JSON 格式）：

sh
oxlint --init

Oxlint 会自动在当前工作目录中查找 .oxlintrc.json 或 oxlint.config.ts。你也可以显式指定配置文件（注意：这将禁用嵌套配置查找）：

sh
oxlint -c ./oxlintrc.json
# 或者
oxlint --config ./oxlintrc.json

注意事项：

  • .oxlintrc.json 支持注释（类似 jsonc）。
  • 配置格式旨在与 ESLint v8 的格式兼容（eslintrc.json）。
  • 一个目录中可以使用 .oxlintrc.json 或 oxlint.config.ts 中的任意一种，但不能同时使用两者。

一个最小的配置如下所示：

.oxlintrc.json
json
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "categories": {
    "correctness": "warn"
  },
  "rules": {
    "eslint/no-unused-vars": "error"
  }
}

TypeScript 配置文件（oxlint.config.ts） ​

Oxlint 还支持名为 oxlint.config.ts 的 TypeScript 配置文件。

oxlint.config.ts
ts
import { defineConfig } from "oxlint";

export default defineConfig({
  categories: {
    correctness: "warn",
  },
  rules: {
    "eslint/no-unused-vars": "error",
  },
});

注意事项：

  • 文件必须命名为 oxlint.config.ts（即使通过 --config 传递也需如此）。
  • 默认导出必须是一个对象，并且应使用 defineConfig 包裹以获得类型支持。
  • TypeScript 配置需要基于 Node 的 oxlint 包（JS 运行时）。如果你使用的是独立二进制文件，请改用 .oxlintrc.json。
  • TypeScript 配置需要可执行 TypeScript 的 Node 运行时。

配置文件格式 ​

配置文件可以是以下两种形式之一：

  • 一个 JSON 对象（.oxlintrc.json）
  • 一个默认导出配置对象的 TypeScript 模块（oxlint.config.ts）

最常见的顶层字段包括：

  • rules：启用或禁用规则，设置严重程度，以及配置规则选项。
  • categories：通过具有相似意图的规则组来启用或禁用。
  • plugins：启用内置插件以提供额外规则。
  • jsPlugins：配置 JavaScript 插件（实验性功能）。
  • overrides：对不同文件模式应用不同的配置。
  • extends：从其他文件继承配置。
  • ignorePatterns：从配置文件中忽略额外的文件。
  • env：为常见环境启用预定义全局变量。
  • globals：声明自定义全局变量为只读或可写。
  • settings：由多个规则共享的插件级配置。

有关完整字段列表，请参阅 配置文件参考。

配置规则 ​

规则在 rules 下进行配置。

规则值可以是以下任意一种：

  • 严重程度（"off"、"warn"、"error"），或
  • 数组 [severity, options]

如果规则名称是唯一的，你可以不带插件前缀进行配置。例如，no-console 等同于 eslint/no-console。

.oxlintrc.json
json
{
  "rules": {
    "no-alert": "error",
    "oxc/approx-constant": "warn",
    "no-plusplus": "off"
  }
}

严重程度值 ​

Oxlint 接受 ESLint 风格的严重程度：

  • 允许规则："off"、"allow"
  • 规则警告："warn"
  • 规则错误："error"、"deny"

规则选项 ​

要配置规则选项，请使用数组形式：

.oxlintrc.json
json
{
  "rules": {
    "no-plusplus": ["error", { "allowForLoopAfterthoughts": true }]
  }
}

所有可用规则及其配置选项，请参见 规则参考。

从 CLI 覆盖严重程度 ​

为了快速试验，你可以通过命令行调整严重程度，使用以下选项：

  • -A / --allow
  • -W / --warn
  • -D / --deny

参数按从左到右顺序应用：

sh
oxlint -D no-alert -W oxc/approx-constant -A no-plusplus

使用类别启用规则组 ​

类别允许你启用或禁用具有相似意图的一组规则。默认情况下，Oxlint 启用 correctness 类别中的规则。

使用 categories 配置类别：

.oxlintrc.json
json
{
  "categories": {
    "correctness": "error",
    "suspicious": "warn",
    "pedantic": "off"
  }
}

可用类别包括：

  • correctness：明显错误或无用的代码
  • suspicious：很可能错误或无用的代码
  • pedantic：更严格的规定，可能产生误报
  • perf：旨在提升运行时性能的规则
  • style：符合习惯且一致的样式规则
  • restriction：禁止特定模式或特性的规则
  • nursery：正在开发中、可能变动的规则

你也可以通过 CLI 使用相同的 -A、-W、-D 选项更改类别：

sh
oxlint -D correctness -D suspicious

配置插件 ​

插件用于扩展可用规则集。

Oxlint 在 Rust 中原生支持许多流行的插件。这提供了广泛的规则覆盖，而无需庞大的 JavaScript 依赖树。详情请见 原生插件。

使用 plugins 配置插件。设置 plugins 会覆盖默认的插件集合，因此该数组应包含你希望启用的所有插件：

.oxlintrc.json
json
{
  "plugins": ["unicorn", "typescript", "oxc"]
}

禁用所有默认插件的方法：

.oxlintrc.json
json
{
  "plugins": []
}

关于插件的详细信息及诸如 --import-plugin 等 CLI 标志，请参见 原生插件。

配置 JS 插件（实验性） ​

Oxlint 还通过 jsPlugins 支持 JavaScript 插件。此功能旨在与现有的 ESLint 插件保持兼容，并支持高级集成。

注意事项：

  • JS 插件为实验性功能，不受语义版本控制约束。

JS 插件可以以字符串形式声明，或作为带有别名的对象：

.oxlintrc.json
json
{
  "jsPlugins": [
    "eslint-plugin-playwright",
    { "name": "my-eslint-react", "specifier": "eslint-plugin-react" }
  ]
}

某些插件名称被保留，因为它们已在 Rust 中原生实现（例如 react、unicorn、typescript、oxc、import、jest、vitest、jsx-a11y、nextjs）。如果需要某个保留插件的 JavaScript 版本，请为其指定自定义 name 以避免冲突。

更多详情请参见 JS 插件。

按文件模式应用配置 ​

使用 overrides 可对不同文件（如测试文件、脚本或仅限 TypeScript 的路径）应用不同的配置。

overrides 是一个对象数组。每个覆盖项可以包含：

  • files：glob 模式
  • rules：规则配置（与顶层 rules 形式相同）
  • env：环境配置（与顶层 env 形式相同）
  • globals：全局变量配置（与顶层 globals 形式相同）
  • plugins：可选地为该覆盖项更改启用的插件
  • jsPlugins：该覆盖项的 JS 插件（实验性功能）

示例：

.oxlintrc.json
json
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "rules": {
    "no-console": "error"
  },
  "overrides": [
    {
      "files": ["scripts/*.js"],
      "rules": {
        "no-console": "off"
      }
    },
    {
      "files": ["**/*.{ts,tsx}"],
      "plugins": ["typescript"],
      "rules": {
        "typescript/no-explicit-any": "error"
      }
    },
    {
      "files": ["**/test/**"],
      "plugins": ["jest"],
      "env": {
        "jest": true
      },
      "rules": {
        "jest/no-disabled-tests": "off"
      }
    }
  ]
}

继承共享配置 ​

使用 extends 从其他配置文件继承配置。

extends 中的路径相对于声明 extends 的配置文件进行解析。配置按从前往后的顺序合并，后面的条目会覆盖前面的条目。

.oxlintrc.json
json
{
  "extends": ["./configs/base.json", "./configs/frontend.json"]
}
oxlint.config.ts
ts
import baseConfig from "./configs/base.ts";
import frontendConfig from "./configs/frontend.ts";
import { defineConfig } from "oxlint";

export default defineConfig({
  extends: [baseConfig, frontendConfig],
});

配置环境和全局变量 ​

使用 env 为常见环境（如浏览器或 Node）启用预定义全局变量。

使用 globals 声明项目特定的全局变量，标记其为可写或只读，或禁用原本存在的全局变量。

.oxlintrc.json
json
{
  "env": {
    "es6": true
  },
  "globals": {
    "MY_GLOBAL": "readonly",
    "Promise": "off"
  }
}

globals 接受以下值：

  • "readonly"、"readable" 或 false
  • "writable"、"writeable" 或 true
  • "off" 以禁用某个全局变量

插件设置 ​

使用 settings 进行多个规则共享的插件级配置。

示例（多包仓库 + React + jsx-a11y）：

.oxlintrc.json
json
{
  "settings": {
    "next": {
      "rootDir": "apps/dashboard/"
    },
    "react": {
      "linkComponents": [{ "name": "Link", "linkAttribute": "to" }]
    },
    "jsx-a11y": {
      "components": {
        "Link": "a",
        "Button": "button"
      }
    }
  }
}

下一步 ​

© 2026 VoidZero Inc. 及 Oxc 贡献者。