类型感知的代码检查

🌐 Type-Aware Linting

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

🌐 Type-aware linting enables rules that rely on TypeScript’s type system, such as detecting unhandled promises or unsafe assignments. In Oxlint, type-aware linting is provided by tsgolint and integrated into the Oxlint CLI and configuration system.

此功能目前处于测试阶段。规则覆盖、性能和兼容性正在持续改进。

🌐 This feature is currently alpha. Rule coverage, performance, and compatibility continue to improve.

概览

🌐 Overview

Oxlint 在两个组件之间划分职责：

🌐 Oxlint separates responsibilities between two components:

• Oxlint (Rust) 处理文件遍历、忽略逻辑、配置、非类型感知规则以及报告。
• tsgolint (Go) 使用 typescript-go 构建 TypeScript 程序，并执行类型感知规则，将结构化的诊断结果返回给 Oxlint。

安装

🌐 Installation

类型感知的代码检查需要额外的依赖：

🌐 Type-aware linting requires an additional dependency:

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

运行类型感知的代码检查

🌐 Running type-aware linting

要使用类型感知的 lint 功能运行 Oxlint，必须传递 --type-aware 标志：

🌐 To run Oxlint with type-aware linting, you must pass the --type-aware flag:

oxlint --type-aware

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

🌐 When enabled, Oxlint runs standard rules and type-aware rules in the typescript/* namespace.

类型感知的代码检查是可选的，除非提供了该选项，否则不会运行。

🌐 Type-aware linting is opt-in and does not run unless the flag is provided.

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

🌐 In editor and LSP-based integrations like VS Code, type-aware linting can be enabled by setting the typeAware option to true, see the Editors page for more information.

单体仓库和构建输出

🌐 Monorepos and build outputs

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

🌐 Type-aware linting requires resolved type information.

在单体仓库中：

🌐 In monorepos:

• 构建依赖包以使 .d.ts 文件可用
• 在运行之前确保已安装依赖

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

类型检查诊断

🌐 Type checking diagnostics

启用类型检查，以便在显示 lint 结果的同时报告 TypeScript 错误：

🌐 Enable type checking to report TypeScript errors alongside lint results:

oxlint --type-aware --type-check

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

🌐 This mode can replace a separate tsc --noEmit step in CI:

# before
tsc --noEmit
oxlint

# after
oxlint --type-aware --type-check

配置类型感知规则

🌐 Configuring type-aware rules

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

🌐 Type-aware rules are configured like other Oxlint rules.

.oxlintrc.json

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

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

🌐 Rules support the same options as their typescript-eslint equivalents.

.oxlintrc.json

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

关闭评论

🌐 Disable comments

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

🌐 Type-aware rules support inline disable comments:

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

使用以下方法报告未使用的禁用注释：

🌐 Report unused disable comments with:

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

TypeScript 兼容性

🌐 TypeScript compatibility

类型感知的代码检查由 typescript-go 提供支持。

🌐 Type-aware linting is powered by typescript-go.

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

请参阅 TypeScript 迁移指南 了解详细信息，并考虑使用 ts5to6 来升级你的 tsconfig 文件。

🌐 See the TypeScript migration guide for more details, and consider using ts5to6 to upgrade your tsconfig file.

稳定性说明

🌐 Stability notes

类型感知型 linting 处于 alpha 阶段：

🌐 Type-aware linting is alpha:

• 规则覆盖不完整
• 非常大的代码库可能会遇到高内存使用问题
• 性能持续提升

故障排除

🌐 Troubleshooting

性能与调试

🌐 Performance and debugging

如果类型感知的代码检查速度慢或占用大量内存：

🌐 If type-aware linting is slow or uses excessive memory:

1. 更新两个工具：

• oxlint
• oxlint-tsgolint

2. 启用调试日志：

OXC_LOG=debug oxlint --type-aware

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

🌐 Example output (showing key timing milestones):

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 项目。此阶段应当很快。如果速度很慢，请提交问题。
• 程序代码检查 ([N/M] Running linter on program...)：每个 TypeScript 项目都会单独进行代码检查。运行时间明显较长的程序可能表明类型解析开销较大或项目规模过大。
  • 查找源文件数量异常多的程序（例如，Program created with 26140 source files）。这可能表明 tsconfig includes/excludes 配置错误，导致引入了像 node_modules 这样的不必要文件。
  • 每个记录的文件路径都表示该文件正在进行代码检查。文件之间较长的时间间隔可能表明某些文件的类型解析耗时较长。

常见性能问题

🌐 Common performance issues

根 tsconfig 包含的文件太多

🌐 Root tsconfig includes too many files

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

🌐 A root tsconfig.json with overly broad include patterns can inadvertently include all files in the repository, causing significant slowdowns:

tsconfig.json

{
  "include": ["**/*"] // ❌ Catches everything
}

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

🌐 This configuration pulls in build outputs and other files that shouldn't be type-checked.

修复： 明确定义 include 模式的作用域，并添加适当的 exclude 条目：

tsconfig.json

{
  "include": ["src/**/*"], // ✅ Only source files
  "exclude": ["dist", "build", "coverage"] // node_modules are excluded by default
}

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

🌐 For monorepos, ensure the root tsconfig.json does not include source files directly:

tsconfig.json

{
  "files": []
}

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

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

如果你在一个程序中看到成千上万的文件，检查 tsconfig 的 include/exclude 设置。

🌐 If you see thousands of files in a single program, check that tsconfig's include/exclude settings.

下一步

🌐 Next steps

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