ty 类型检查器文件发现与排除完全指南：include / exclude / gitignore 模式与虚拟环境处理

ty 类型检查器文件发现与排除完全指南：include / exclude / gitignore 模式与虚拟环境处理

【免费下载链接】tyAn extremely fast Python type checker and language server, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ty2/ty

导读

ty（一个用 Rust 编写的极速 Python 类型检查器）默认会自动发现项目中的全部 Python 文件，但在真实工程中，生成代码目录、构建产物、虚拟环境、测试夹具等通常都不应纳入类型检查。本文基于 ty 的官方文档与仓库源码，系统讲解通过src.include、src.exclude、respect-ignore-files等配置项精准控制文件发现范围的方法，并深入解析其 gitignore 风格的 glob 语法、默认排除清单、CLI 显式传参与虚拟环境处理策略。读完本文，你将能在pyproject.toml或ty.toml中准确配置 ty 的检查范围，并理解这些配置在底层是如何生效的。

文件发现机制概述

ty 会在项目中自动发现所有 Python 文件。这一发现过程受两类因素共同约束：

1. 显式配置：通过src.include与src.exclude设置（见 src 配置参考）指定搜索与排除范围；
2. 隐式规则：默认排除的常见目录清单，以及.gitignore、.ignore等忽略文件的尊重策略。

配置文件的组织方式遵循 ty 的通用规则（见 配置指南）：可以在项目根目录或其最近的父目录放置pyproject.toml（配置写在[tool.ty]表下）或ty.toml（省略[tool.ty]前缀）。ty.toml优先于pyproject.toml；项目级配置优先于用户级配置（~/.config/ty/ty.toml）；命令行参数又优先于所有持久化配置。

用 include 与 exclude 划定检查范围

ty 通过src.include和src.exclude两个配置项控制检查哪些文件。以下配置会让 ty 检查src和tests目录下的全部 Python 文件，但跳过src/generated目录：

=== "pyproject.toml"

```toml [tool.ty.src] include = ["src", "tests"] exclude = ["src/generated"] ```

=== "ty.toml"

```toml [src] include = ["src", "tests"] exclude = ["src/generated"] ```

需要注意两点优先级规则（见 src.exclude 参考 与 src.include 参考）：

• exclude优先于include：即使某个路径同时命中 include 与 exclude，它也会被排除；
• exclude为空时默认值并非“无”：ty 会默认排除一系列常见目录（详见下文“默认排除清单”），除非你用取反模式显式撤销。

从源码结构看，include/exclude的匹配发生在 ty 的文件收集阶段（ty 的配置定义集中在 Rust 工作区的ty_projectcrate 中，例如crates/ty_project/src/metadata/options.rs中的Options结构体），先由 include 确定候选集合，再由 exclude 做减法，最终进入类型检查流水线。

默认排除清单与取反（!）模式

ty 默认排除一批几乎在所有工程中都不应检查的目录（完整清单见 src.exclude 参考）：

**/.bzr/ **/.direnv/ **/.eggs/ **/.git/ **/.git-rewrite/ **/.hg/ **/.mypy_cache/ **/.nox/ **/.pants.d/ **/.pytype/ **/.ruff_cache/ **/.svn/ **/.tox/ **/.venv/ **/__pypackages__/ **/_build/ **/buck-out/ **/dist/ **/node_modules/ **/venv/

这份清单覆盖了主流版本控制目录（.git、.hg、.bzr、.svn）、缓存目录（.mypy_cache、.ruff_cache、.pytype、.pants.d）、虚拟环境（.venv、venv、__pypackages__）以及常见构建产物（dist、_build、buck-out、node_modules、.eggs）等。

如果确实需要让某个默认排除的目录参与检查，可以用前导!的取反 exclude将其“重新纳入”。例如，把默认排除清单中的build目录恢复为可检查：

=== "pyproject.toml"

```toml [tool.ty.src] # Remove `build` from the excluded directories. exclude = ["!**/build/"] ```

=== "ty.toml"

```toml [src] # Remove `build` from the excluded directories. exclude = ["!**/build/"] ```

同理，要恢复dist可用exclude = ["!dist"]。注意取反模式同样遵循下文介绍的 glob 语法，且带斜杠的!**/build/只匹配目录（含其内容），不带斜杠的!dist同时匹配文件与目录。

尊重.gitignore与.ignore文件

默认情况下（respect-ignore-files为true），ty 会忽略.ignore、.gitignore、.git/info/exclude以及全局 gitignore 文件中列出的文件（见 respect-ignore-files 参考）。这意味着你现有的 Git 忽略规则会直接作用于 ty 的文件发现，无需在 ty 配置中重复维护一份排除清单。

如果希望 ty 忽略这些文件（例如想完全由include/exclude控制范围），可以关闭该功能：

=== "pyproject.toml"

```toml [tool.ty.src] respect-ignore-files = false ```

=== "ty.toml"

```toml [src] respect-ignore-files = false ```

命令行中对应的是--respect-ignore-files与--no-respect-ignore-files开关（见 ty check 命令行参考）。

显式传参：命令行路径总是被包含

你可以把要检查的路径直接作为ty check的位置参数传入，例如：

ty check src scripts/benchmark.py

即使这些路径本会被exclude过滤或忽略文件排除，只要以位置参数显式传入ty check，它们就一定会被包含在检查范围内。也就是说，显式传参拥有最高优先级，是“无论如何都要检查这些文件”的可靠手段。

这一行为也带来一个配套选项：如果你希望即使显式传入的路径也强制受排除规则约束，可以使用--force-exclude（见 ty check 命令行参考）。此外，与文件发现相关的 CLI 选项还包括：

• --exclude <exclude>：以 gitignore 风格模式在命令行追加排除规则，支持如tests/、*.tmp、**/__pycache__/**等写法（见 --exclude 参考）；
• --exclude-scripts/--include-scripts：控制是否排除含 PEP 723 内联脚本元数据的文件（详见下文）；
• --config-file <path>与TY_CONFIG_FILE环境变量：指定配置文件。

include / exclude 的 glob 语法详解

include与exclude均采用 gitignore 风格的 glob 模式，语法规则如下（两条配置的详细说明分别见 include 参考 与 exclude 参考）：

模式是锚定的

所有模式都相对于项目根目录锚定。例如src只匹配<project_root>/src，不会匹配<project_root>/test/src。同理，exclude 模式src只排除<project_root>/src，不会排除<project_root>/test/src。要匹配任意层级下名为src的目录，应使用前缀匹配**/src。

⚠️ 性能警告

前缀 include 模式（如**/src）会显著拖慢 Python 文件发现的速度，因为 ty 必须遍历更多目录层级来做匹配。若非必要，优先使用锚定的相对路径。

语法来源

所有接受模式的字段都采用 PEP 639 中定义的“精简可移植 glob 语法”（reduced portable glob syntax），并额外支持用反斜杠\转义字符。这意味着如果你需要匹配模式中的特殊字符（如字面量的*或?），可以通过转义来实现。

排除含内联元数据的脚本：exclude-scripts

除路径匹配外，ty 还支持按文件内容特征排除：src.exclude-scripts用于排除包含 PEP 723 内联脚本元数据（inline script metadata）的文件，除非它们在命令行中被显式传入（见 exclude-scripts 参考）。默认值为false（即默认检查这类脚本）：

=== "pyproject.toml"

```toml [tool.ty.src] exclude-scripts = true ```

=== "ty.toml"

```toml [src] exclude-scripts = true ```

命令行对应--exclude-scripts与反向的--include-scripts（见 ty check 命令行参考）。

虚拟环境（venv）的排除问题

问题背景

从 Python 3.13 开始，venv模块会在虚拟环境根目录自动写入一个.gitignore文件。由于 ty 默认尊重.gitignore（respect-ignore-files = true），虚拟环境内的文件会被自动排除，ty 不会对其中的文件发出诊断。

然而在使用更早版本的 Python 时，虚拟环境根目录没有.gitignore，ty 可能会对虚拟环境内的文件产生诊断——尤其是当虚拟环境恰好在项目根目录下（如.venv），而它又不在 ty 的默认排除清单生效范围之外的情况下。

解决方案

方案一：为虚拟环境补充一个.gitignore。例如名为.venv的虚拟环境：

echo "*" > .venv/.gitignore

这样 ty 会尊重该文件，从而忽略.venv内的全部内容。

方案二：把虚拟环境目录加入项目根目录的.gitignore或.ignore文件，效果相同。

进阶：针对特定文件的 overrides 排除

除了全局的include/exclude，ty 还提供了overrides机制，可以在同一份配置中针对特定文件/目录应用不同的规则配置（见 overrides 参考）。每个 override 自带include与exclude列表（语法与上文一致），用于圈定其作用范围：

# 在 tests 与生成文件中放宽规则 [[tool.ty.overrides]] include = ["tests/**", "**/test_*.py"] [tool.ty.overrides.rules] possibly-unresolved-reference = "warn"

# 忽略生成目录中的规则，但保留关键文件 [[tool.ty.overrides]] include = ["generated/**"] exclude = ["generated/important.py"] [tool.ty.overrides.rules] possibly-unresolved-reference = "ignore"

override 内的exclude优先于同一 override 内的include；多个 override 同时命中同一文件时，后定义的生效；override 规则优先于全局规则。

配置优先级小结

综合来看，ty 的文件发现与排除遵循以下优先级（从高到低）：

1. 命令行显式路径参数：传入ty check的路径必定被包含（除非使用--force-exclude）；
2. 命令行选项：--exclude、--respect-ignore-files/--no-respect-ignore-files、--exclude-scripts等覆盖配置文件；
3. 项目级配置文件（ty.toml优先于pyproject.toml的[tool.ty]表）：src.include、src.exclude、respect-ignore-files、exclude-scripts；
4. 用户级配置（~/.config/ty/ty.toml等）：与项目级配置合并，数组类设置会拼接；
5. 内置默认规则：默认排除清单与.gitignore/.ignore尊重策略。

理解这条链路，你就能在大型仓库、多分支生成代码、混合虚拟环境等复杂场景下，精确地让 ty 只检查你真正关心的 Python 文件，既避免噪音诊断拖慢反馈速度，也防止生成代码中的问题被遗漏。

【免费下载链接】tyAn extremely fast Python type checker and language server, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ty2/ty