基于类型的代码检查

基于类型的代码检查使能够利用 TypeScript 类型系统的规则成为可能，例如检测未处理的异步操作或不安全的赋值。在 Oxlint 中，这一功能由 tsgolint 提供，并已集成到 Oxlint CLI 及其配置系统中。

此功能目前处于 开发中（alpha） 阶段，规则覆盖范围、性能和兼容性仍在持续改进中。

概览

Oxlint 将职责分离为两个组件：

• Oxlint (Rust) 负责文件遍历、忽略逻辑、配置管理、非基于类型规则以及报告生成。

• tsgolint (Go) 使用 typescript-go 构建 TypeScript 项目，并执行基于类型的规则，将结构化的诊断信息返回给 Oxlint。

安装

基于类型的代码检查需要额外依赖项：

npm

npm add -D oxlint-tsgolint@latest

pnpm

pnpm add -D oxlint-tsgolint@latest

yarn

yarn add -D oxlint-tsgolint@latest

bun

bun add -D oxlint-tsgolint@latest

运行基于类型的代码检查

要使用基于类型的代码检查运行 Oxlint，必须传递 --type-aware 标志：

oxlint --type-aware

启用后，Oxlint 将运行标准规则以及 typescript/* 命名空间下的基于类型规则。

基于类型的代码检查是可选功能，除非提供该标志，否则不会运行。

在编辑器及基于 LSP 的集成（如 VS Code）中，可通过将 typeAware 选项设置为 true 来启用基于类型的代码检查，更多详情请参阅 编辑器 页面。

多包仓库与构建输出

基于类型的代码检查需要解析后的类型信息。

在多包仓库中：

• 构建依赖的包，以确保 .d.ts 文件可用
• 确保在运行前已安装所有依赖项

pnpm install
pnpm -r build
oxlint --type-aware

启用类型检查诊断

启用类型检查，以便在代码检查结果中同时报告 TypeScript 错误：

oxlint --type-aware --type-check

该模式可以替代 CI 流水线中的独立 tsc --noEmit 步骤：

# 之前
tsc --noEmit
oxlint

# 之后
oxlint --type-aware --type-check

配置基于类型规则

基于类型规则的配置方式与其他 Oxlint 规则相同。

.oxlintrc.json

{
  "plugins": ["typescript"],
  "rules": {
    "typescript/no-floating-promises": "error",
    "typescript/no-unsafe-assignment": "warn"
  }
}

规则支持与它们对应的 typescript-eslint 版本相同的选项。

.oxlintrc.json

{
  "plugins": ["typescript"],
  "rules": {
    "typescript/no-floating-promises": ["error", { "ignoreVoid": true }]
  }
}

禁用注释

基于类型规则支持内联禁用注释：

// oxlint-disable-next-line typescript/no-floating-promises
doSomethingAsync();

通过以下命令报告未使用的禁用指令：

oxlint --type-aware --report-unused-disable-directives

TypeScript 兼容性

基于类型的代码检查由 typescript-go 驱动。

• 需要 TypeScript 7.0+
• 某些旧版 tsconfig 选项不受支持（如 tsconfig.json 中的 baseUrl）
• 如果你正在使用在 TypeScript 6.0 已弃用或在 TypeScript 7.0 移除的配置选项/特性，需先迁移代码库
• 当启用 --type-check 时，无效选项会被报告

有关详细信息，请参阅 TypeScript 升级指南，并考虑使用 ts5to6 升级你的 tsconfig 文件。

稳定性说明

基于类型的代码检查目前处于 开发中（alpha） 阶段：

• 规则覆盖不完整
• 极大型代码库可能会遇到高内存使用情况
• 性能仍在持续优化中

故障排查

性能与调试

如果基于类型的代码检查运行缓慢或占用过多内存：

1. 更新两个工具：

• oxlint
• oxlint-tsgolint

2. 启用调试日志：

OXC_LOG=debug oxlint --type-aware

示例输出（显示关键时间点）：

2026/01/01 12:00:00.000000 启动 tsgolint
2026/01/01 12:00:00.001000 开始分配文件到项目。总文件数：259
2026/01/01 12:00:01.000000 文件分配完成。总项目数：8。未匹配文件数：75
2026/01/01 12:00:01.001000 启动带有 12 个工作线程的代码检查器
2026/01/01 12:00:01.001000 工作负载分布：8 个项目
2026/01/01 12:00:01.002000 [1/8] 对项目 /path/to/project/jsconfig.json 执行代码检查
...
2026/01/01 12:00:01.100000 [4/8] 对项目 /path/to/project/tsconfig.json 执行代码检查
2026/01/01 12:00:02.500000 项目创建完成，包含 26140 个源文件
2026/01/01 12:00:14.000000 /path/to/project/oxlint-plugin.mts
...
2026/01/01 12:00:14.100000 [5/8] 对项目 /path/to/project/apps/tsconfig.json 执行代码检查
...
2026/01/01 12:00:15.000000 代码检查完成
共处理 259 个文件，使用 161 条规则，12 个线程，耗时 16.4 秒。

如何解读日志：

• 文件分配阶段（Starting to assign files... → Done assigning files...）：将源文件映射到其 tsconfig 项目。该阶段应很快。若耗时过长，请提交问题。
• 项目代码检查（[N/M] Running linter on program...）：每个 TypeScript 项目分别进行检查。若某项目耗时显著过长，可能表明类型解析开销大或项目过大。
  • 注意是否存在源文件数量异常高的项目（如 Program created with 26140 source files）。这可能表示 tsconfig includes/excludes 配置不当，错误地包含了如 node_modules 等不应被检查的文件。
  • 每条日志中的文件路径表示该文件正在被检查的时间点。文件之间出现长时间间隔，可能意味着某些文件的类型解析开销较大。

常见性能问题

根目录的 tsconfig 包含过多文件

一个过于宽泛的 include 模式的根 tsconfig.json 可能无意中包含仓库中所有文件，导致显著性能下降：

tsconfig.json

{
  "include": ["**/*"] // ❌ 包含全部内容
}

该配置会引入构建输出及其他不应被类型检查的文件。

修复方法： 明确限定 include 模式，并添加适当的 exclude 条目：

tsconfig.json

{
  "include": ["src/**/*"], // ✅ 仅源文件
  "exclude": ["dist", "build", "coverage"] // node_modules 默认已排除
}

对于多包仓库，确保根 tsconfig.json 不直接包含源文件：

tsconfig.json

{
  "files": []
}

诊断问题： 启用调试日志，查找源文件数量异常高的项目：

2026/01/01 12:00:02.500000 项目创建完成，包含 26140 个源文件

如果发现单个项目中有数千个文件，请检查 tsconfig 的 include/exclude 设置是否正确。

下一步

• 查看 已实现规则
• 在 https://github.com/oxc-project/tsgolint 报告问题