Oxc

新增 Linter 规则 ​

为 Oxlint 贡献最简便的方式就是新增 Lint 规则。

本指南将带你完成整个流程，以 ESLint 的 no-debugger 规则为例。

TIP

请先阅读 环境配置指南。

第 1 步：选择规则 ​

我们的 Linter 产品计划与进度 Issue 跟踪了所有需要实现的 ESLint 插件规则。从中挑选一个你感兴趣的插件，找到一个尚未实现的规则。

重要：由于 ESLint 兼容的 JavaScript 插件支持现已可用，我们不再计划新增基于 Rust 的新插件。但是，我们非常鼓励为现有插件新增规则。如果你认为某个规则或插件用 Rust 编写会更好，请在提交 PR 之前先发起讨论。

大多数 ESLint 规则文档页面都包含该规则的源代码链接。参考源码有助于你的实现。

第 2 步：生成规则 ​

接下来，运行 rulegen 脚本为新规则生成模板代码。

bash
just new-rule no-debugger

这将：

  1. 在 crates/oxc_linter/src/rules/<plugin-name>/<rule-name>.rs 创建新文件，包含规则实现的起点以及从 ESLint 移植的所有测试用例
  2. 在 rules.rs 中注册规则到对应的 mod
  3. 将规则添加到 oxc_macros::declare_all_lint_rules!

对于属于其他插件的规则，你需要使用该插件对应的 rulegen 脚本。

TIP

不带参数运行 just 可查看所有可用命令。

bash
just new-rule [name]            # eslint 核心规则
just new-jest-rule [name]       # eslint-plugin-jest
just new-ts-rule [name]         # @typescript-eslint/eslint-plugin
just new-unicorn-rule [name]    # eslint-plugin-unicorn
just new-import-rule [name]     # eslint-plugin-import
just new-react-rule [name]      # eslint-plugin-react 和 eslint-plugin-react-hooks
just new-jsx-a11y-rule [name]   # eslint-plugin-jsx-a11y
just new-oxc-rule [name]        # oxc 自己的规则
just new-nextjs-rule [name]     # eslint-plugin-next
just new-jsdoc-rule [name]      # eslint-plugin-jsdoc
just new-react-perf-rule [name] # eslint-plugin-react-perf
just new-n-rule [name]          # eslint-plugin-n
just new-promise-rule [name]    # eslint-plugin-promise
just new-vitest-rule [name]     # eslint-plugin-vitest

生成的文件大致如下：

点击展开
rust
use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::Span;

use crate::{
    context::LintContext,
    fixer::{RuleFix, RuleFixer},
    rule::Rule,
    AstNode,
};

#[derive(Debug, Default, Clone)]
pub struct NoDebugger;

declare_oxc_lint!(
    /// ### 作用
    ///
    ///
    /// ### 为什么不推荐
    ///
    ///
    /// ### 示例
    ///
    /// 违反此规则的 **错误** 代码示例：
    /// ```js
    /// FIXME: 如果缺少示例或代码存在语法错误，测试将失败。
    /// ```
    ///
    /// 符合此规则的 **正确** 代码示例：
    /// ```js
    /// FIXME: 如果缺少示例或代码存在语法错误，测试将失败。
    /// ```
    NoDebugger,
    nursery, // TODO: 将类别更改为 `correctness`、`suspicious`、`pedantic`、`perf`、`restriction` 或 `style`
             // 详见 <https://oxc.rs/contribute/linter.html#rule-category>

    pending  // TODO: 描述修复能力。如果无法修复则删除，
             // 如果认为可以添加但不知道如何实现，则保留为 'pending'
             // 选项包括 'fix'、'fix_dangerous'、'suggestion' 和 'conditional_fix_suggestion'
);

impl Rule for NoDebugger {
    fn run<'a>(&self, node: &AstNode<'a>, ctx: &LintContext<'a>) {}
}

#[test]
fn test() {
    use crate::tester::Tester;
    let pass = vec!["var test = { debugger: 1 }; test.debugger;"];
    let fail = vec!["if (foo) debugger"];
    Tester::new(NoDebugger::NAME, pass, fail).test_and_snapshot();
}

你的规则现在应该可以运行了！使用 cargo test -p oxc_linter 进行测试。由于你还没有实现规则，测试应该会失败。

第 3 步：填写模板 ​

文档 ​

填写各个文档部分。

  • 提供清晰简洁的规则作用说明。
  • 解释为什么此规则重要以及它能防止哪些不良行为。
  • 提供违反规则和符合规则的代码示例。

请记住，我们使用这些文档为本网站生成规则文档页面，因此请确保你的文档清晰易懂！

配置文档 ​

如果你的规则有配置选项，你需要记录它们。你应该通过自动生成文档的系统来完成。rulegen 脚本应该已经为你自动生成了部分内容。

每个配置选项都应该通过向规则结构体添加字段来定义：

rust
pub struct RuleName {
  option_name: bool,
  another_option: String,
  yet_another_option: Vec<CompactStr>,
}

或者，你也可以定义一个单独的 Config 结构体来保存所有配置选项：

rust
pub struct RuleName(Box<RuleNameConfig>);

pub struct RuleNameConfig {
  option_name: bool,
}

配置选项应该派生 JsonSchema，并添加 serde 装饰器，如下所示：

rust
use schemars::JsonSchema;

#[derive(Debug, Default, Clone, JsonSchema)]
#[serde(rename_all = "camelCase", default)]
pub struct RuleName {
  option_name: bool,
}

为每个字段添加文档注释（///）来描述该选项，例如：

rust
use schemars::JsonSchema;

#[derive(Debug, Default, Clone, JsonSchema)]
#[serde(rename_all = "camelCase", default)]
pub struct RuleName {
  /// 在评估 baz 时是否检查 foo 和 bar。
  /// 注释可以尽可能长，以充分描述该选项。
  option_name: bool,
}

每个选项的默认值和类型将自动从结构体定义中提取，不应在文档注释中提及。

有关如何正确记录各种规则配置选项的数十个示例，请参阅此 Issue。

你可以通过运行 cargo run -p website -- linter-rules --rule-docs target/rule-docs --git-ref $(git rev-parse HEAD) 来查看生成的文档，然后打开 target/rule-docs/<plugin-name>/<rule-name>.md。

规则类别 ​

首先，为规则选择最合适的规则类别。请记住，correctness 类别的规则会默认运行，因此选择此类别时要谨慎。在 declare_oxc_lint! 宏中设置你的类别。

修复器状态 ​

如果规则有修复器，在 declare_oxc_lint! 中注册它提供的修复类型。如果你不擅长实现修复器，也可以使用 pending 作为占位符。这有助于其他贡献者后续发现并实现缺失的修复器。

诊断信息 ​

创建一个函数来为规则违规创建诊断信息。遵循以下原则：

  1. message 应该是关于什么有问题的祈使句，而不是描述规则的作用。
  2. help 消息应该是命令式的语句，告诉用户如何修复问题。
rust
fn no_debugger_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("不允许使用 `debugger` 语句")
        .with_help("删除此 `debugger` 语句")
        .with_label(span)
}
rust
fn no_debugger_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("禁止 `debugger` 语句")
        .with_help("不允许使用 `debugger` 语句。")
        .with_label(span)

第 4 步：规则实现 ​

阅读规则的源代码以了解其工作原理。虽然 Oxlint 与 ESLint 类似，但规则不太可能直接移植。

ESLint 规则有一个 create 函数，返回一个对象，其键是触发规则的 AST 节点，值是在这些节点上运行 lint 的函数。Oxlint 规则在少数几个触发器之一上运行，每个触发器都来自 Rule trait：

  1. 在每个 AST 节点上运行（通过 run）
  2. 在每个符号上运行（通过 run_on_symbol）
  3. 在整个文件上运行一次（通过 run_once）

对于 no-debugger，我们正在查找 DebuggerStatement 节点，因此我们将使用 run。以下是规则的简化版本：

点击展开
rust
use oxc_ast::AstKind;
use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::Span;

use crate::{context::LintContext, rule::Rule, AstNode};

fn no_debugger_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("不允许使用 `debugger` 语句")
        .with_label(span)
}

#[derive(Debug, Default, Clone)]
pub struct NoDebugger;

declare_oxc_lint!(
    /// ### 作用
    /// 检查是否使用了 `debugger` 语句
    ///
    /// ### 为什么不推荐
    /// 当没有连接调试器时，`debugger` 语句不会影响功能。
    /// 它们通常是最常见的意外调试残留。
    ///
    /// ### 示例
    ///
    /// 违反此规则的 **错误** 代码示例：
    /// ```js
    /// async function main() {
    ///     const data = await getData();
    ///     const result = complexCalculation(data);
    ///     debugger;
    /// }
    /// ```
    NoDebugger,
    correctness
);

impl Rule for NoDebugger {
    // 在 AST 中的每个节点上运行
    fn run<'a>(&self, node: &AstNode<'a>, ctx: &LintContext<'a>) {
        // `debugger` 语句有自己的 AST 类型
        if let AstKind::DebuggerStatement(stmt) = node.kind() {
            // 报告违规
            ctx.diagnostic(no_debugger_diagnostic(stmt.span));
        }
    }
}

TIP

你需要熟悉 Semantic 中存储的数据，这是语义分析期间提取的所有数据的位置。你还需要熟悉 AST 结构。这里最重要的两个数据结构是 AstNode 和 AstKind

第 5 步：测试 ​

要在每次更改时测试你的规则，运行：

bash
just watch "cargo test -p oxc_linter -- rule-name"

或者只测试一次，运行：

bash
cargo test -p oxc_linter -- rule-name
# 或者
cargo insta test -p oxc_linter -- rule-name

Oxlint 使用 cargo insta 进行快照测试。如果快照已更改或刚刚创建，cargo test 将失败。你可以运行 cargo insta test -p oxc_linter 来不在测试结果中看到差异。你可以通过运行 cargo insta review 来查看快照，或者跳过查看并使用 cargo insta accept 接受所有更改。

当你准备好提交 PR 时，运行 just ready 或 just r 在本地运行 CI 检查。你也可以运行 just fix 来自动修复任何 lint、格式或拼写问题。一旦 just ready 通过，创建 PR，维护者将审查你的更改。

一般建议 ​

将错误消息定位到最短的代码跨度 ​

我们希望用户专注于有问题的代码，而不是解读错误消息来确定代码的哪部分有错误。

使用 let-else 语句 ​

如果你发现自己深度嵌套 if-let 语句，考虑改用 let-else。

TIP

CodeAesthetic 的 never-nesting 视频 更详细地解释了这个概念。

rust
// let-else 更易读
fn run<'a>(&self, node: &AstNode<'a>, ctx: &LintContext<'a>) {
    let AstKind::JSXOpeningElement(jsx_opening_elem) = node.kind() else {
        return;
    };
    let Some(expr) = container.expression.as_expression() else {
        return;
    };
    let Expression::BooleanLiteral(expr) = expr.without_parenthesized() else {
        return;
    };
    // ...
}
rust
// 深度嵌套难以阅读
fn run<'a>(&self, node: &AstNode<'a>, ctx: &LintContext<'a>) {
    if let AstKind::JSXOpeningElement(jsx_opening_elem) = node.kind() {
        if let Some(expr) = container.expression.as_expression() {
            if let Expression::BooleanLiteral(expr) = expr.without_parenthesized() {
                // ...
            }
        }
    }
}

尽可能使用 CompactStr ​

尽可能减少分配对于 oxc 的性能至关重要。String 类型需要在堆上分配内存，这会消耗内存和 CPU 周期。可以使用 CompactStr 将小字符串内联存储（在 64 位系统上最多 24 字节）到栈上，这意味着我们不需要分配内存。如果字符串太大而无法内联存储，它将分配所需的空间。CompactStr 几乎可以在任何使用 String 或 &str 类型的地方使用，与 String 类型相比可以节省大量内存和 CPU 周期。

rust
struct Element {
  name: CompactStr
}

let element = Element {
  name: "div".into()
};
rust
struct Element {
  name: String
}

let element = Element {
  name: "div".to_string()
};

© 2026 VoidZero Inc. and Oxc contributors.