配置
🌐 Configuration
Oxlint 开箱即用，但大多数团队会提交一个配置文件，以确保本地运行、编辑器和持续集成中的代码检查保持一致。
🌐 Oxlint works out of the box, but most teams commit a configuration file to keep linting consistent across local runs, editors, and CI.
本页面侧重于项目配置：规则、类别、插件、覆盖项和共享设置。
🌐 This page focuses on project configuration: rules, categories, plugins, overrides, and shared settings.
创建配置文件
🌐 Create a config file
在当前目录生成一个初始配置：
🌐 To generate a starter config in the current directory:
oxlint --initOxlint 会自动在当前工作目录中查找 .oxlintrc.json。你也可以显式传递配置（请注意，这将禁用嵌套配置查找）：
🌐 Oxlint automatically looks for a .oxlintrc.json in the current working directory. You can also pass a config explicitly (note that this will disable nested config lookup):
oxlint -c ./oxlintrc.json
# or
oxlint --config ./oxlintrc.json注意：
🌐 Notes:
- 只支持
.json配置文件，但 oxlint 配置文件支持注释（类似 jsonc）。 - 该配置格式旨在与 ESLint v8 的格式（
eslintrc.json）兼容。
一个最小配置如下所示：
🌐 A minimal configuration looks like this:
{
"$schema": "./node_modules/oxlint/configuration_schema.json",
"categories": {
"correctness": "warn"
},
"rules": {
"eslint/no-unused-vars": "error"
}
}配置文件格式
🌐 Configuration file format
配置文件是一个 JSON 对象。最常见的顶层字段有：
🌐 A configuration file is a JSON object. The most common top-level fields are:
rules：启用或禁用规则，设置严重性，并配置规则选项。categories：启用具有相似意图的规则组。plugins：启用提供附加规则的内置插件。jsPlugins：配置 JavaScript 插件（实验性功能）。overrides：对不同的文件模式应用不同的配置。extends：从其他文件继承配置。ignorePatterns：忽略配置文件中的附加文件。env：为常见环境启用预定义全局变量。globals：将自定义全局声明为只读或可写。settings：由多个规则共享的插件范围配置。
有关字段的完整列表，请参阅 配置文件参考。
🌐 For a complete list of fields, see the Config file reference.
配置规则
🌐 Configure rules
规则在 rules 下配置。
🌐 Rules are configured under rules.
规则值可以是:
🌐 A rule value is either:
- 严重程度（
"off"、"warn"、"error"），或 [severity, options]数组
如果规则名称是唯一的，你可以在不加插件前缀的情况下配置它。例如，no-console 与 eslint/no-console 是相同的。
🌐 If a rule name is unique, you can configure it without a plugin prefix. For example, no-console is the same as eslint/no-console.
{
"rules": {
"no-alert": "error",
"oxc/approx-constant": "warn",
"no-plusplus": "off"
}
}严重程度值
🌐 Severity values
Oxlint 接受 ESLint 风格的严重性：
🌐 Oxlint accepts ESLint-style severities:
- 允许规则：
"off"，0，"allow" - 规则警告：
"warn"，1 - 规则错误：
"error"、2、"deny"
规则选项
🌐 Rule options
要配置规则选项，请使用数组：
🌐 To configure rule options, use an array:
{
"rules": {
"no-plusplus": ["error", { "allowForLoopAfterthoughts": true }]
}
}所有可用规则及其配置选项都列在规则参考中。
🌐 All available rules, and their configuration options, are listed in the Rules reference.
从命令行覆盖严重性
🌐 Override severity from the CLI
对于快速实验，你可以通过命令行调整严重性等级：
🌐 For quick experiments, you can adjust severity from the command line using:
-A/--allow-W/--warn-D/--deny
参数从左到右应用：
🌐 Arguments are applied from left to right:
oxlint -D no-alert -W oxc/approx-constant -A no-plusplus启用带有类别的规则组
🌐 Enable groups of rules with categories
类别允许你启用或禁用具有相似意图的一组规则。默认情况下，Oxlint 会启用 correctness 类别中的规则。
🌐 Categories let you enable or disable sets of rules with similar intent. By default, Oxlint enables rules in the correctness category.
使用 categories 配置类别：
🌐 Configure categories using categories:
{
"categories": {
"correctness": "error",
"suspicious": "warn",
"pedantic": "off"
}
}可用类别包括：
🌐 Available categories include:
correctness：绝对错误或无用的代码suspicious：可能是错误或无用的代码pedantic：可能产生误报的额外严格规则perf：旨在提高运行时性能的规则style：惯用和一致的风格规则restriction：禁止特定模式或功能的规则nursery：正在制定中的规则，可能会有所变动
你也可以使用相同的 -A、-W 和 -D 选项从命令行更改类别：
🌐 You can also change categories from the CLI with the same -A, -W, and -D options:
oxlint -D correctness -D suspicious配置插件
🌐 Configure plugins
插件扩展了可用规则的集合。
🌐 Plugins extend the set of available rules.
Oxlint 原生支持许多流行的 Rust 插件。这在不依赖大量 JavaScript 库的情况下提供了广泛的规则覆盖。详见 原生插件。
🌐 Oxlint supports many popular plugins natively in Rust. This provides broad rule coverage without a large JavaScript dependency tree. See Native Plugins.
使用 plugins 配置插件。设置 plugins 会覆盖默认插件集合，因此数组应包含你想启用的所有内容：
🌐 Configure plugins using plugins. Setting plugins overwrites the default plugin set, so the array should include everything you want enabled:
{
"plugins": ["unicorn", "typescript", "oxc"]
}要禁用所有默认插件：
🌐 To disable all default plugins:
{
"plugins": []
}有关插件详细信息和 CLI 标志（如 --import-plugin），请参阅 本地插件。
🌐 For plugin details and CLI flags such as --import-plugin, see Native Plugins.
配置 JS 插件（实验性）
🌐 Configure JS plugins (experimental)
Oxlint 也通过 jsPlugins 支持 JavaScript 插件。这旨在与现有的 ESLint 插件及高级集成兼容。
🌐 Oxlint also supports JavaScript plugins via jsPlugins. This is intended for compatibility with existing ESLint plugins and advanced integrations.
注意：
🌐 Notes:
- JS 插件是实验性的，不遵循语义化版本控制。
- 当前语言服务器不支持 JS 插件。
JS 插件可以声明为字符串，或作为带有别名的对象：
🌐 JS plugins can be declared as strings, or as objects with an alias:
{
"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 以避免冲突。
🌐 Some plugin names are reserved because they are implemented natively in Rust (for example react, unicorn, typescript, oxc, import, jest, vitest, jsx-a11y, nextjs). If you need the JavaScript version of a reserved plugin, give it a custom name to avoid conflicts.
详情请参见 JS 插件。
🌐 For details, see JS plugins.
按文件模式应用配置
🌐 Apply configuration by file pattern
使用 overrides 将不同的配置应用到不同的文件，例如测试文件、脚本或仅限 TypeScript 的路径。
🌐 Use overrides to apply different configuration to different files, such as tests, scripts, or TypeScript-only paths.
overrides 是一个对象数组。每个覆盖项可以包括：
files：全局模式rules：规则配置（与顶层rules形状相同）env：环境配置（与顶层env形状相同）globals：全局配置（形状与顶层globals相同）plugins：可选择更改此覆盖使用的插件jsPlugins：用于此覆盖的 JS 插件（实验性）
示例：
🌐 Example:
{
"$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"
}
}
]
}扩展共享配置
🌐 Extend shared configs
使用 extends 从其他配置文件继承。
🌐 Use extends to inherit from other configuration files.
extends 中的路径是相对于声明 extends 的配置文件解析的。配置从第一个到最后一个进行合并，后面的条目会覆盖前面的条目。
🌐 Paths in extends are resolved relative to the configuration file that declares extends. Configs are merged from first to last, with later entries overriding earlier ones.
{
"extends": ["./configs/base.json", "./configs/frontend.json"]
}配置环境和全局设置
🌐 Configure environments and globals
使用 env 来为常见环境（如浏览器或 Node）启用预定义的全局变量。
🌐 Use env to enable predefined globals for common environments such as browser or node.
使用 globals 来声明项目特定的全局变量，标记它们为可写或只读，或禁用本来会存在的全局变量。
🌐 Use globals to declare project-specific globals, mark them writable or readonly, or disable a global that would otherwise be present.
{
"env": {
"es6": true
},
"globals": {
"MY_GLOBAL": "readonly",
"Promise": "off"
}
}globals 接受：
"readonly"或"readable"或false"writable"或"writeable"或true"off"用于禁用全局
插件设置
🌐 Plugin settings
使用 settings 来进行多个规则共享的插件级配置。
🌐 Use settings for plugin-wide configuration shared by multiple rules.
示例（单一代码库 + React + jsx-a11y）：
🌐 Example (monorepo + React + jsx-a11y):
{
"settings": {
"next": {
"rootDir": "apps/dashboard/"
},
"react": {
"linkComponents": [{ "name": "Link", "linkAttribute": "to" }]
},
"jsx-a11y": {
"components": {
"Link": "a",
"Button": "button"
}
}
}
}下一步
🌐 Next steps