Oxc

调试 ​

OXC_LOG 环境变量 ​

OXC_LOG 用于在 oxlint 与 oxfmt 中启用运行时 tracing。若未设置，则完全不发日志以实现零开销。

基础用法 ​

bash
# 为 oxlint 开启 debug 日志
OXC_LOG=debug oxlint

# 为 oxfmt 开启 debug 日志
OXC_LOG=debug oxfmt

# 使用 import 插件时为 resolver 记录 trace
OXC_LOG=oxc_resolver oxlint --import-plugin

# 为 formatter 记录 trace
OXC_LOG=oxc_formatter oxfmt

过滤器语法 ​

OXC_LOG 使用 tracing-subscriber 的过滤器语法：

模式说明
debug为所有模块开启 debug 级别
trace为所有模块开启 trace 级别
oxc_resolver启用 oxc_resolver 模块的所有日志
oxc_resolver=debug仅 debug 级别的 oxc_resolver
oxc_resolver=tracetrace 级别的 oxc_resolver
oxc_formatter,oxc_resolver同时启用多个模块

输出位置 ​

日志写到 stderr，避免干扰 linter 的诊断或格式化结果在 stdout。oxfmt 中还会附带线程名与 span 耗时，便于分析多线程行为。

常见场景 ​

列出正在被处理的文件：

bash
OXC_LOG=debug oxlint
OXC_LOG=debug oxfmt

排查模块解析问题：

bash
OXC_LOG=oxc_resolver=debug oxlint --import-plugin

rust-lldb ​

可对 debug 构建使用 rust-lldb 获取 panic 信息。

编译时开启调试符号（见下方 Cargo.toml 示例），构建二进制后附加调试器运行。

启用调试符号：

toml
[profile.release]
debug = true
strip = false
panic = "unwind"

编译：

bash
cargo build --release --bin oxlint --features allocator

启动：

bash
rust-lldb -- ./target/release/oxlint

进入后在 LLDB 中按 r 运行程序。

在 VS Code 里调试 TypeScript ​

根据 TypeScript 仓库的调试指南：

  • 将 .vscode/launch.template.json 重命名为 launch.json
  • 添加 tests/cases/compiler/foo.ts
  • 将 "${fileBasenameNoExtension}" 改成 foo.ts
  • 在 TS 源码中设置断点
  • 菜单「运行 — 调试」或按 F5
  • 调试时，tsc 会先评估全局 .d.ts，再进入目标测试文件
  • src/compiler/debug.ts 中的 Debug.formatXXX(value) 可打印枚举等
  • 在「监视」里观察表达式

在 VS Code 里调试 Linter ​

可借助 CodeLLDB，在任意地方的 npm 项目里调试 Linter。

在 .vscode/launch.json 中按需修改：

  • cwd：测试项目的绝对路径
  • args：传给 linter 的参数
json
{
  "type": "lldb",
  "request": "launch",
  "name": "Debug Oxlint",
  "cargo": {
    "env": {
      "RUSTFLAGS": "-g"
    },
    "args": ["build", "--bin=oxlint", "--package=oxlint"],
    "filter": {
      "name": "oxlint",
      "kind": "bin"
    }
  },
  "cwd": "PATH-TO-TEST-PROJECT", 
  "args": ["--ARGS-TO-OXLINT"] 
}

打开 VS Code 调试面板，选择「Debug Oxlint」启动。会以指定 cwd 拉起进程，相当于在测试工程中运行 linter 并附加调试。

© 2026 VoidZero Inc. and Oxc contributors.