增量检查未生效的根本原因是缓存被绕过：修改pyproject.toml/mypy.ini配置、__init__.py等顶层模块，或使用--follow-imports=normal但存在未安装包，均触发全量重检；可通过--verbose日志、.mypy_cache目录及二次运行耗时验证缓存是否工作。
增量检查为什么没生效？
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 还报老错。
立即学习“Python免费学习笔记（深入）”；
- 最安全的清理方式是
rm -rf .mypy_cache/，不要只删部分子目录 - 如果只想清特定模块，可以用
mypy --clear-cache，但它只清内存映射，不删磁盘文件，效果有限 - Python 升级后（比如从 3.11 切到 3.12），旧缓存目录不会自动废弃，mypy 可能读错版本对应的 cache，此时必须手动删
缓存机制本身不复杂，但它的边界条件很具体——它只信任“没动过”的文件和“没变过”的配置。一旦其中一环松动，它就退回全量模式，而且不提醒你。
