ty 类型检查器 `replace-imports-with-any` 配置全面指南：用 glob 模式将模块导入替换为 `Any` 并抑制导入诊断

在引入第三方依赖时，某些包缺乏类型信息、类型存根质量参差不齐，或在迁移旧代码库时无法立即补齐类型标注。此时类型检查器会持续抛出 unresolved-import 等诊断噪音，干扰对真实问题的判断。Ruff 仓库中基于 Rust 构建的类型检查器 ty（相关实现见 crates/ty）为此提供了 replace-imports-with-any 配置项：它使用 glob 模式匹配模块名，将匹配到的导入类型统一替换为 typing.Any，并同时抑制相关导入诊断。本文以 ty 的官方测试文档 crates/ty_python_semantic/resources/mdtest/import/replace_imports_with_any.md 为骨架，结合 ty 配置文档 与 模块解析源码 展开讲解，读完你将掌握该配置的完整语法、匹配规则、与 allowed-unresolved-imports 的差异，以及覆盖不可解析模块、可解析模块、相对导入等各类场景的实战配置方案。

一、配置定位与核心语义

replace-imports-with-any 属于 [analysis] 配置段，其官方定义为：「一组模块 glob 模式，匹配到的导入将被替换为 typing.Any」。

它的两条核心语义决定了它的行为边界：

1. 当模块无法被解析且匹配模式时，导入被替换为 Any，且不发出任何诊断——这是它作为「兜底」方案的基本场景；
2. 即使模块存在且携带完整的类型信息，匹配到的模块类型同样会被替换为 Any——这是它与仅抑制诊断的配置（如 allowed-unresolved-imports）最本质的区别。

与之对比，配置文档 crates/ty/docs/configuration.md 中明确指出：与 allowed-unresolved-imports 不同，该配置「会替换模块的类型信息，即使模块可以被解析；对于匹配的模块，导入诊断被无条件抑制」。

默认值：[] 类型：list[str]

配置位置

该配置支持在 pyproject.toml 与 ty.toml 两处声明。pyproject.toml 中使用 [tool.ty.analysis] 段：

[tool.ty.analysis]
# Replace all pandas and numpy imports with Any
replace-imports-with-any = ["pandas.**", "numpy.**"]

ty.toml 中使用 [analysis] 段：

[analysis]
# Replace all pandas and numpy imports with Any
replace-imports-with-any = ["pandas.**", "numpy.**"]

此外该选项也可在 pyproject.toml 的 [tool.ty.overrides.analysis] 或 ty.toml 的 [overrides.analysis] 段中按文件/目录覆盖配置，例如：

[tool.ty.overrides.analysis]
replace-imports-with-any = ["pandas.**", "numpy.**"]

从实现角度看，配置解析位于 crates/ty_project/src/metadata/options.rs，它通过 build_module_glob_set 将字符串列表编译为模块 glob 集合，并以 Option<Vec<RangedValue<String>>> 形式承载原始字符串以便报告配置来源。在类型推断的配置模型 crates/ty_python_semantic/src/lib.rs 中，它与 allowed_unresolved_imports 一同作为 ModuleGlobSet 存储，默认值为 ModuleGlobSet::empty()。

二、Glob 模式语法（与 allowed-unresolved-imports 共用）

文档明确指出：该配置的语法采用 glob 模式，语法细节参见 allowed-unresolved-imports。ty 的 glob 模式由 crates/ty_module_resolver/src/module_glob.rs 中的 ModuleGlobSet 实现，其底层将 glob 编译为正则表达式集合 RegexSet 进行高效匹配。模式语法要点如下：

模式	匹配	不匹配
test	精确匹配模块 test	test.foo、testing
test.*	test.foo、test.bar	test、test.foo.bar
*.test	foo.test、bar.test	test、foo.bar.test
test.**	test、test.foo、test.foo.bar	testing
**.test	test、foo.test、foo.bar.test	test.foo
test.**.bar	test.bar、test.foo.bar、test.a.b.bar	test、test.bar.foo
**	任意模块	—

具体规则：

• * 匹配零个或多个字符，但不匹配 .；
• ** 匹配零个或多个模块组件，且必须独立构成一个组件：**foo、foo** 均非法并会报错，超过两个连续 * 的序列同样非法；
• 模式可以相互组合。例如，要匹配「第一个组件包含子串 test」的所有模块，可用 *test*.**；
• 多个模式同时命中时，后面的条目优先（last-match-wins，语义与 gitignore 类似）；
• 以 ! 开头的模式为否定模式，用于排除匹配的模块。

否定模式与优先级的实现细节在 ModuleGlobSet::matches 中：它找到按添加顺序的「最后一个匹配的模式」，若该模式带 negated 标记则返回 Exclude，否则返回 Include，没有任何模式命中时返回 None。调用方（如类型推断代码）通过 is_include() 判断是否命中。

三、核心场景一：不可解析模块被替换为 Any

这是 replace-imports-with-any 最基本的使用场景。假设项目引入了一个无法解析的模块 foo：

[analysis]
replace-imports-with-any = ["foo.**"]

import foo
from foo import bar
from foo.sub import baz

reveal_type(foo)  # revealed: Any
reveal_type(bar)  # revealed: Any
reveal_type(baz)  # revealed: Any

注意 foo.** 这种「结尾 **」模式：它匹配任何以 foo 开头的模块名，包括 foo 本身、foo.bar、foo.bar.baz。因此无论是以 import foo 直接导入包，还是 from foo import bar、from foo.sub import baz 访问其子模块，全部命中，类型统一呈现为 Any，且不会产生 unresolved-import 诊断。

从实现上印证，类型推断代码 crates/ty_python_semantic/src/types/infer/builder/imports.rs 在 infer_import_definition 中首先检查 replace_imports_with_any.matches(&full_module_name).is_include()，命中则直接以 Type::any() 建立声明与绑定并提前返回，完全跳过后续的模块解析流程。在 report_unresolved_import 中，命中 replace_imports_with_any（或 allowed_unresolved_imports）的模块也会提前 return，从而抑制诊断。

四、核心场景二：可解析模块同样被替换为 Any

这是该配置与「仅抑制诊断」类方案的关键差异点：即使模块真实存在、携带完整类型信息，只要匹配模式，其类型依然被替换为 Any。

假设包结构如下：

pkg/__init__.py
pkg/sub.py
main.py

配置：

[analysis]
replace-imports-with-any = ["pkg.**"]

pkg/__init__.py：

x: int = 1

pkg/sub.py：

y: str = "hello"

main.py：

from pkg import x
from pkg.sub import y
import pkg

reveal_type(x)  # revealed: Any
reveal_type(y)  # revealed: Any
reveal_type(pkg)  # revealed: Any

尽管 x 的真实标注是 int、y 的真实标注是 str，但匹配 pkg.** 后三者全部呈现为 Any。这表示：该配置不会去读取、解析或信任匹配模块的类型信息——它适用于「包本身可以解析、但你不信任其类型信息或不想被其拖慢分析」的场景。

实现上，infer_import_definition 与 infer_import_from_definition（针对 from ... import ... 语句）都在解析模块之前先执行该匹配检查，命中即以 Type::any() 直接绑定，从而绕过了对模块成员、子模块乃至 __getattr__ 的静态分析。

五、Glob 模式实战：前缀匹配多个模块

利用 * 通配符可以一次性覆盖多个顶层模块。例如希望将 aws、awscli、awscli.customizations 等所有「以 aws 开头」的模块替换为 Any：

[analysis]
replace-imports-with-any = ["aws*.**"]

import aws
import awscli
import awscli.customizations

reveal_type(aws)  # revealed: Any
reveal_type(awscli)  # revealed: Any
reveal_type(awscli.customizations)  # revealed: Any

这里 aws*.** 的含义是「第一个组件以 aws 开头的任意模块」：* 匹配 aws 后的任意字符（如 awscli），. ** 匹配后续任意数量的组件（如 customizations）。同理，若要匹配第一个组件包含子串 test 的所有模块，可写 *test*.**。

六、否定模式：白名单例外

通过 ! 前缀可以在整体替换的范围内保留个别模块的真实类型。例如希望 pkg.** 全部替换为 Any，但保留 pkg.keep 的类型信息：

[analysis]
replace-imports-with-any = ["pkg.**", "!pkg.keep"]

pkg/__init__.py（空文件）：

pkg/keep.py：

value: int = 1

main.py：

from pkg.keep import value
from pkg.skip import other

reveal_type(value)  # revealed: int
reveal_type(other)  # revealed: Any

pkg.keep 被否定模式 !pkg.keep 排除，因此 value 保留真实类型 int；而 pkg.skip 命中正向模式 pkg.**，other 被替换为 Any。

注意优先级规则：多个模式同时命中时，列表中更靠后的模式胜出。因此在 ["pkg.**", "!pkg.keep"] 中，pkg.keep 同时命中两个模式，但 !pkg.keep 在后，最终判定为排除（Exclude）。若调换顺序为 ["!pkg.keep", "pkg.**"]，则 pkg.keep 会因更靠后的 pkg.** 而重新被包含。这一「后写优先」语义与 gitignore 一致，也适用于该配置的兄弟选项 allowed-unresolved-imports（可参见其 mdtest 文档 crates/ty_python_semantic/resources/mdtest/import/allowed_unresolved_imports.md 中对正/负模式排列顺序的专门测试）。

七、相对导入：基于模块绝对路径匹配

相对导入的匹配发生在模块的绝对路径上：只要相对导入解析后的绝对模块名命中模式，替换规则就会生效。例如：

[analysis]
replace-imports-with-any = ["**.foo", "bar"]

package/__init__.py（空文件）：

package/foo.py：

val = 1

package/main.py：

from .foo import val

# .bar would not match "bar" rule because the absolute import is package.bar
from .bar import val2  # error: [unresolved-import]

reveal_type(val)  # revealed: Any

要点有两处：

1. from .foo import val 的绝对模块名是 package.foo，命中 **.foo（匹配任何以 foo 结尾的模块），因此 val 被替换为 Any；
2. from .bar import val2 的绝对模块名是 package.bar。虽然配置中有字面模式 "bar"，但字面模式只精确匹配模块名 bar，而绝对路径是 package.bar，因此不命中，最终报出 error: [unresolved-import]。

这一设计也呼应了配置文档中的示例说明：**.foo 这类「开头 **」模式匹配任何以 foo 结尾的模块名（包括 foo、bar.foo、baz.bar.foo）。相对导入在 crates/ty_python_semantic/src/types/infer/builder/imports.rs 中经由 ModuleName::from_import_statement 先归一化为绝对模块名，再做匹配与解析，这正是「基于绝对路径匹配」的实现基础。

八、未匹配模块不受影响

模式之外的模块保持正常的类型推断与诊断行为：

[analysis]
replace-imports-with-any = ["skipped.**"]

real_module.py：

value: int = 42

main.py：

from real_module import value

reveal_type(value)  # revealed: int

real_module 不匹配 skipped.**，因此照常解析，value 保持真实类型 int。该配置只影响命中模式的模块，不会引入任何全局性的类型降级。

九、实现原理与调用链小结

将上述行为映射到源码，可总结出该配置的完整调用链（均在 crates/ty_python_semantic/src/types/infer/builder/imports.rs）：

• 配置存储：TySettings 中的 replace_imports_with_any: ModuleGlobSet（crates/ty_python_semantic/src/lib.rs），由 crates/ty_project/src/metadata/options.rs 从 pyproject.toml / ty.toml 解析并编译；
• 匹配引擎：ModuleGlobSet::matches 返回 Include / Exclude / None，is_include() 判定命中（crates/ty_module_resolver/src/module_glob.rs）；
• 导入类型替换：infer_import_definition（处理 import foo）与 infer_import_from_definition（处理 from foo import bar）在解析前先查该配置，命中即以 Type::any() 绑定；
• 诊断抑制：report_unresolved_import 对命中该配置（或 allowed_unresolved_imports）的模块提前返回，不再上报 UNRESOLVED_IMPORT；check_direct_dependency 对命中模块同样跳过 MISSING_DIRECT_DEPENDENCY 检查，避免「缺少直接依赖」这类额外噪音。

这套链路保证了「类型替换」与「诊断抑制」在语义上的一致性：凡被替换为 Any 的导入，都不会再产生与解析失败或缺失依赖相关的错误。

十、与 allowed-unresolved-imports 的选型对比

维度	replace-imports-with-any	allowed-unresolved-imports
匹配模块类型	替换为 typing.Any	保持 unresolved（不替换）
可解析模块	仍替换为 Any（类型信息被丢弃）	不受影响，照常使用真实类型
诊断抑制	命中即无条件抑制导入诊断	命中即抑制 unresolved 诊断
典型用途	信任度低/无类型的第三方包，统一降级为 Any	仅想静默「确实解析不到」的模块，保留其真实类型检查能力
语法	相同的 glob 模式（*、**、! 否定、后写优先）	相同的 glob 模式（*、**、! 否定、后写优先）

选择建议：若某个包根本无法解析、且你不关心它的类型（例如历史遗留的可选依赖），二者皆可；若某个包可以解析但你不信任其类型标注（或解析开销过大），只能用 replace-imports-with-any；若只想安静地放过「确定缺失」的模块、同时保留对所有已解析模块的严格检查，则应选用 allowed-unresolved-imports。

十一、实战建议

1. 先小范围再铺开：不要一上来就写 ["**"] 把全部导入降级为 Any——这会彻底失去类型检查价值。建议先用 reveal_type 逐个确认问题模块，再以具体包名前缀（如 pandas.**、numpy.**）精确配置；
2. 善用否定模式做例外：["pkg.**", "!pkg.keep"] 这类「整体替换 + 白名单保留」的组合，能在降级大部分模块的同时，为核心模块保留完整类型检查；
3. 注意模式顺序：由于后写优先，否定模式应放在对应的正向模式之后；需要「先全部排除、再放行个别」时则反过来排列；
4. 利用 overrides 做局部覆盖：在不同目录/文件中需要不同替换策略时，可通过 [tool.ty.overrides.analysis] 按路径覆盖该配置；
5. 与其它导入诊断配合：该配置同时抑制 unresolved-import 与 missing-direct-dependency 类诊断，适用于「明知缺少类型信息或依赖尚未就绪」的过渡期，待依赖补齐后应移除以恢复完整检查。