Oxc

配置 ​

Oxlint 开箱即用，但大多数团队会提交一个配置文件（.oxlintrc.json 或 oxlint.config.ts），以保持本地运行、编辑器和 CI 之间的 lint 一致性。

本页面专注于项目配置：规则、类别、插件、覆盖和共享设置。

创建配置文件 ​

在当前目录生成一个初始配置（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 运行时（Node v22.18+ 或 v24+）。

配置文件格式 ​

配置文件可以是 JSON 对象（.oxlintrc.json）或默认导出配置对象的 TypeScript 模块（oxlint.config.ts）。最常见的顶层字段包括：

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

完整的字段列表请参见 配置文件参考。

配置 linter 选项 ​

使用 options 进行 linter 级行为配置。完整列表请参见 配置文件参考。

示例：

json
{
  "options": {
    "typeAware": true,
    "typeCheck": true,
    "maxWarnings": 10
  }
}
ts
import { defineConfig } from "oxlint";

export default defineConfig({
  options: {
    typeAware: true,
    typeCheck: true,
    maxWarnings: 10,
  },
});
  • options.typeAware 相当于在 CLI 上传递 --type-aware。
  • options.typeCheck（实验性）相当于在 CLI 上传递 --type-check。
  • options.maxWarnings 相当于在 CLI 上传递 --max-warnings。

当 CLI 和配置值都存在时，CLI 标志优先。

options.typeAware 和 options.typeCheck 仅在根配置文件中支持。

配置规则 ​

规则在 rules 下配置。

规则值可以是：

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

如果规则来自 ESLint 核心且其名称唯一，您可以不带插件前缀配置它。例如，no-console 与 eslint/no-console 相同。

json
{
  "rules": {
    "no-alert": "error",
    "oxc/approx-constant": "warn",
    "no-plusplus": "off",
    "eslint/prefer-const": ["error", { "destructuring": "any" }]
  }
}
ts
import { defineConfig } from "oxlint";

export default defineConfig({
  rules: {
    "no-alert": "error",
    "oxc/approx-constant": "warn",
    "no-plusplus": "off",
    "eslint/prefer-const": ["error", { destructuring: "any" }],
  },
});

严重程度值 ​

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

  • 禁用规则："off" 或 "allow"
  • 规则警告："warn"
  • 规则错误："error" 或 "deny"

规则选项 ​

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

json
{
  "rules": {
    "no-plusplus": ["error", { "allowForLoopAfterthoughts": true }]
  }
}
ts
import { defineConfig } from "oxlint";

export default defineConfig({
  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 配置类别：

json
{
  "categories": {
    "correctness": "error",
    "suspicious": "warn",
    "pedantic": "off"
  }
}
ts
import { defineConfig } from "oxlint";

export default defineConfig({
  categories: {
    correctness: "error",
    suspicious: "warn",
    pedantic: "off",
  },
});

可用类别包括：

  • correctness：确实错误或无用的代码
  • suspicious：可能错误或无用的代码
  • pedantic：可能存在误报的额外严格规则
  • perf：旨在提高运行时性能的规则
  • style：惯用和一致的样式规则
  • restriction：禁止特定模式或功能的规则
  • nursery：正在开发中可能更改的规则

您也可以使用相同的 -A、-W 和 -D 选项从 CLI 更改类别：

sh
oxlint -D correctness -D suspicious

配置插件 ​

插件扩展了可用规则集。

Oxlint 在 Rust 中原生支持许多流行插件。这提供了广泛的规则覆盖，而没有大量的 JavaScript 依赖树。参见 原生插件。

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

json
{
  "plugins": ["unicorn", "typescript", "oxc"]
}
ts
import { defineConfig } from "oxlint";

export default defineConfig({
  plugins: ["unicorn", "typescript", "oxc"],
});

要禁用所有默认插件：

json
{
  "plugins": []
}
ts
import { defineConfig } from "oxlint";

export default defineConfig({
  plugins: [],
});

有关插件详情和 CLI 标志（如 --import-plugin），请参见 原生插件。

配置 JS 插件（alpha） ​

Oxlint 也通过 jsPlugins 支持 JavaScript 插件。这旨在与现有 ESLint 插件兼容并提供高级集成。

注意事项：

  • JS 插件处于 alpha 阶段，不受 semver 约束。

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

json
{
  "jsPlugins": [
    "eslint-plugin-playwright",
    { "name": "my-eslint-react", "specifier": "eslint-plugin-react" }
  ]
}
ts
import { defineConfig } from "oxlint";

export default defineConfig({
  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 插件（alpha）

示例：

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"
      }
    }
  ]
}
ts
import { defineConfig } from "oxlint";

export default defineConfig({
  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 的配置文件解析。配置从第一个到最后一个合并，后面的条目覆盖前面的。

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

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

配置环境和全局变量 ​

使用 env 为常见环境（如 browser 或 node）启用预定义的全局变量。

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

json
{
  "env": {
    "es6": true
  },
  "globals": {
    "MY_GLOBAL": "readonly",
    "Promise": "off"
  }
}
ts
import { defineConfig } from "oxlint";

export default defineConfig({
  env: {
    es6: true,
  },
  globals: {
    MY_GLOBAL: "readonly",
    Promise: "off",
  },
});

globals 接受：

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

插件设置 ​

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

示例（monorepo + React + jsx-a11y）：

json
{
  "settings": {
    "next": {
      "rootDir": "apps/dashboard/"
    },
    "react": {
      "linkComponents": [{ "name": "Link", "linkAttribute": "to" }]
    },
    "jsx-a11y": {
      "components": {
        "Link": "a",
        "Button": "button"
      }
    }
  }
}
ts
import { defineConfig } from "oxlint";

export default defineConfig({
  settings: {
    next: {
      rootDir: "apps/dashboard/",
    },
    react: {
      linkComponents: [{ name: "Link", linkAttribute: "to" }],
    },
    "jsx-a11y": {
      components: {
        Link: "a",
        Button: "button",
      },
    },
  },
});

下一步 ​

© 2026 VoidZero Inc. and Oxc contributors.