Oxc

类型感知检查 ​

类型感知检查启用依赖 TypeScript 类型系统的规则，例如检测未处理的 promise 或不安全的赋值。在 Oxlint 中，类型感知检查由 tsgolint 提供，并集成到 Oxlint CLI 和配置系统中。

类型感知检查目前支持 typescript-eslint 的 61 个规则中的 59 个。规则覆盖、性能和兼容性持续改进中。

概述 ​

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

  • Oxlint (Rust) 处理文件遍历、忽略逻辑、配置、非类型感知规则和报告。

  • tsgolint (Go) 使用 typescript-go 构建 TypeScript 程序并执行类型感知规则，将结构化诊断返回给 Oxlint。

安装 ​

类型感知检查需要一个额外的依赖：

sh
npm add -D oxlint-tsgolint@latest
sh
pnpm add -D oxlint-tsgolint@latest
sh
yarn add -D oxlint-tsgolint@latest
sh
bun add -D oxlint-tsgolint@latest

运行类型感知检查 ​

您可以在以下任一位置启用类型感知检查：

  • CLI 标志：--type-aware
  • 根配置：options.typeAware: true

CLI：

bash
oxlint --type-aware

根配置：

json
{
  "options": {
    "typeAware": true
  }
}
ts
import { defineConfig } from "oxlint";

export default defineConfig({
  options: {
    typeAware: true,
  },
});

启用后，Oxlint 会运行标准规则和 typescript/* 命名空间中的类型感知规则。

--type-aware 优先于配置文件。例如，oxlint --type-aware -c .oxlintrc.json 会启用类型感知检查，即使该配置将 options.typeAware 设置为 false。

options.typeAware 和 options.typeCheck 仅在根配置文件中支持。嵌套配置不应设置这些字段。

在编辑器和基于 LSP 的集成（如 VS Code）中，可以通过将 typeAware 选项设置为 true 来启用类型感知检查，更多信息请参阅编辑器页面。

Monorepo 和构建输出 ​

类型感知检查需要解析的类型信息。

在 monorepo 中：

  • 构建依赖包以便 .d.ts 文件可用
  • 确保在运行前安装依赖
bash
pnpm install
pnpm -r build
oxlint --type-aware

类型检查诊断 ​

启用类型检查以报告 TypeScript 错误和 lint 结果：

bash
oxlint --type-aware --type-check

或在根配置中启用：

json
{
  "options": {
    "typeAware": true,
    "typeCheck": true
  }
}
ts
import { defineConfig } from "oxlint";

export default defineConfig({
  options: {
    typeAware: true,
    typeCheck: true,
  },
});

--type-check 优先于配置文件。例如，oxlint --type-check -c .oxlintrc.json 会启用类型检查，即使该配置将 options.typeCheck 设置为 false。

此模式可以替代 CI 中单独的 tsc --noEmit 步骤：

bash
# 之前
tsc --noEmit
oxlint

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

配置类型感知规则 ​

类型感知规则与其他 Oxlint 规则配置方式相同。

json
{
  "plugins": ["typescript"],
  "rules": {
    "typescript/no-floating-promises": "error",
    "typescript/no-unsafe-assignment": "warn"
  }
}
ts
import { defineConfig } from "oxlint";

export default defineConfig({
  plugins: ["typescript"],
  rules: {
    "typescript/no-floating-promises": "error",
    "typescript/no-unsafe-assignment": "warn",
  },
});

规则支持与其 typescript-eslint 等效项相同的选项。

json
{
  "plugins": ["typescript"],
  "rules": {
    "typescript/no-floating-promises": ["error", { "ignoreVoid": true }]
  }
}
ts
import { defineConfig } from "oxlint";

export default defineConfig({
  plugins: ["typescript"],
  rules: {
    "typescript/no-floating-promises": ["error", { ignoreVoid: true }],
  },
});

禁用注释 ​

类型感知规则支持内联禁用注释：

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

报告未使用的禁用注释：

bash
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 文件。

稳定性说明 ​

类型感知检查：

  • 规则覆盖不完整（但非常接近）
  • 非常大的代码库可能会遇到高内存使用
  • 性能持续改进中

故障排除 ​

性能和调试 ​

如果类型感知检查缓慢或使用过多内存：

  1. 更新两个工具：
  • oxlint
  • oxlint-tsgolint
  1. 启用调试日志：
bash
OXC_LOG=debug oxlint --type-aware

示例输出（显示关键计时里程碑）：

2026/01/01 12:00:00.000000 Starting tsgolint
2026/01/01 12:00:00.001000 Starting to assign files to programs. Total files: 259
2026/01/01 12:00:01.000000 Done assigning files to programs. Total programs: 8. Unmatched files: 75
2026/01/01 12:00:01.001000 Starting linter with 12 workers
2026/01/01 12:00:01.001000 Workload distribution: 8 programs
2026/01/01 12:00:01.002000 [1/8] Running linter on program: /path/to/project/jsconfig.json
...
2026/01/01 12:00:01.100000 [4/8] Running linter on program: /path/to/project/tsconfig.json
2026/01/01 12:00:02.500000 Program created with 26140 source files
2026/01/01 12:00:14.000000 /path/to/project/oxlint-plugin.mts
...
2026/01/01 12:00:14.100000 [5/8] Running linter on program: /path/to/project/apps/tsconfig.json
...
2026/01/01 12:00:15.000000 Linting Complete
Finished in 16.4s on 259 files with 161 rules using 12 threads.

如何解读日志：

  • 文件分配阶段（Starting to assign files... → Done assigning files...）：将源文件映射到其 tsconfig 项目。此阶段应该很快。如果缓慢，请提交 issue。
  • 程序 lint（[N/M] Running linter on program...）：每个 TypeScript 项目单独 lint。耗时显著较长的程序可能表示昂贵的类型解析或过大的项目。
    • 查找源文件数量异常多的程序（例如 Program created with 26140 source files）。这可能表示 tsconfig 的 includes/excludes 配置错误，拉入了不必要的文件如 node_modules。
    • 记录的每个文件路径指示该文件何时被 lint。文件之间的大时间间隔可能表示某些文件的类型解析昂贵。

常见性能问题 ​

根 tsconfig 包含太多文件 ​

具有过于宽泛的 include 模式的根 tsconfig.json 可能会无意中包含仓库中的所有文件，导致显著变慢：

tsconfig.json
json
{
  "include": ["**/*"] // ❌ 捕获所有内容
}

此配置会拉入构建输出和其他不应被类型检查的文件。

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

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

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

tsconfig.json
json
{
  "files": []
}

诊断问题： 启用调试日志并查找源文件数量异常多的程序：

2026/01/01 12:00:02.500000 Program created with 26140 source files

如果您看到单个程序中有数千个文件，请检查该 tsconfig 的 include/exclude 设置。

下一步 ​

© 2026 VoidZero Inc. and Oxc contributors.