mypy增量检查与缓存原理详解

mypy的增量检查并非“失效”，而是其缓存机制极为敏感——只要修改了pyproject.toml/mypy.ini中的关键配置、顶层模块（如__init__.py）或存在未安装依赖导致--follow-imports=normal退化，缓存就会被彻底绕过，触发耗时的全量重检；真正高效的增量体验需通过--verbose日志、检查.mypy_cache目录结构及对比二次运行耗时来主动验证，而非依赖默认行为，并注意避免CI清缓存、Python版本升级后残留旧缓存等常见陷阱，才能让类型检查既准确又飞快。

增量检查为什么没生效？

mypy 默认开启增量检查，但实际不提速，大概率是缓存被绕过了。根本原因不是它坏了，而是你改了某些触发全量重检的文件或配置。

• pyproject.toml 或 mypy.ini 里修改了 plugins、disallow_untyped_defs 等影响类型语义的配置项，mypy 会丢弃整个缓存
• 修改了 __init__.py 或任何被其他模块 import 的顶层模块，它会重新计算依赖图，很多文件被迫重检
• 用了 --follow-imports=normal（默认值），但实际项目里有本地未安装的包，mypy 会退回到慢速解析模式，缓存失效

怎么确认缓存是否在工作？

别猜，直接看输出和文件系统。mypy 不会主动告诉你“本次用了缓存”，得自己验证。

• 加 --verbose 运行一次，观察日志里有没有类似 cached: module_x, module_y 的行；没有就说明没走缓存路径
• 检查 .mypy_cache/ 目录是否存在且有内容，特别是子目录名是否对应你的 Python 版本（如 3.11）
• 改一行无关代码（比如注释），再跑 mypy --show-traceback，如果报错位置和上次一样、耗时明显低于首次，基本可判定缓存生效

mypy --incremental 是不是必须加？

不是。从 mypy 0.900 开始，--incremental 已是默认行为，显式加上反而容易让人误以为它是“开关”。真正影响缓存行为的是以下几件事：

• 确保没传 --no-incremental —— 这个 flag 会强制禁用所有缓存逻辑
• 避免混用 mypy 和 mypyc，后者有自己的缓存结构，会污染 .mypy_cache/
• CI 环境里注意清理策略：有些流水线每次清空 workspace，导致缓存永远建不起来；建议保留 .mypy_cache/ 目录（但别提交到 git）

缓存文件能手动删吗？

能，而且有时必须删。缓存不是坚不可摧的，它会因类型信息不一致而卡住，表现是：明明改对了类型，mypy 还报老错。

• 最安全的清理方式是 rm -rf .mypy_cache/，不要只删部分子目录
• 如果只想清特定模块，可以用 mypy --clear-cache，但它只清内存映射，不删磁盘文件，效果有限
• Python 升级后（比如从 3.11 切到 3.12），旧缓存目录不会自动废弃，mypy 可能读错版本对应的 cache，此时必须手动删

缓存机制本身不复杂，但它的边界条件很具体——它只信任“没动过”的文件和“没变过”的配置。一旦其中一环松动，它就退回全量模式，而且不提醒你。

今天关于《mypy增量检查与缓存原理详解》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于的内容请关注golang学习网公众号！