调试

OXC_LOG 环境变量

OXC_LOG 环境变量可在 oxlint 和 oxfmt 中启用运行时追踪。未设置时，日志记录完全禁用，以实现零开销操作。

基本用法

# 为 oxlint 启用调试日志
OXC_LOG=debug oxlint

# 为 oxfmt 启用调试日志
OXC_LOG=debug oxfmt

# 使用导入插件时启用解析器追踪
OXC_LOG=oxc_resolver oxlint --import-plugin

# 启用格式化器追踪
OXC_LOG=oxc_formatter oxfmt

过滤语法

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

模式	描述
debug	为所有模块启用调试级别
trace	为所有模块启用追踪级别
oxc_resolver	启用来自 oxc_resolver 模块的所有日志
oxc_resolver=debug	为 oxc_resolver 启用调试级别
oxc_resolver=trace	为 oxc_resolver 启用追踪级别
oxc_formatter,oxc_resolver	启用多个模块

输出

日志被写入 标准错误（stderr），以避免干扰标准输出上的检查诊断信息或格式化代码。在 oxfmt 中，还包含线程名称和跨度时间信息，以便于调试多线程操作。

常见使用场景

列出正在处理的所有文件：

OXC_LOG=debug oxlint
OXC_LOG=debug oxfmt

调试模块解析问题：

OXC_LOG=oxc_resolver=debug oxlint --import-plugin

rust-lldb

rust-lldb 可用于从调试版本中获取崩溃信息。

启用调试符号：

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

构建二进制文件：

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

运行二进制文件：

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

启动后，按 r 键运行程序。

在 VSCode 中调试 TypeScript

根据其 调试指南，在 TypeScript 仓库中：

• 将 .vscode/launch.template.json 重命名为 launch.json
• 添加 tests/cases/compiler/foo.ts
• 将 "${fileBasenameNoExtension}" 改为 foo.ts
• 在 TypeScript 源码中的某处设置断点
• 从菜单“运行 - 调试”进入，或按下 F5
• 调试过程中，tsc 会在目标测试文件之前评估全局 .d.ts 文件
• 可使用 src/compiler/debug.ts 中的 Debug.formatXXX(value) 打印枚举值
• 使用“监视”（WATCH）区域来“查看”感兴趣的值

在 VSCode 中调试 Linter

可以轻松地使用 CodeLLDB 来调试位于其他位置的 npm 项目中的 Linter。

在 .vscode/launch.json 中，根据需要修改配置字段：

• cwd：npm 项目的绝对路径
• args：传递给 linter 的参数

{
  "type": "lldb",
  "request": "launch",
  "name": "调试 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"] 
}

打开 VSCode 的调试面板并选择 调试 Oxlint，然后开始调试。

调试过程将按照指定的 cwd 启动，类似于在测试项目中运行 linter 并附加调试器。