近日，Python 静态类型检查工具 mypy 的 2.0 版本曝出一项令开发者困惑的缓存异常：当两次调用 mypy 时，若其中一次传递了 --num-workers 参数（用于指定并行检查的进程数），另一次未传递该参数，那么第一次运行生成的缓存文件在第二次运行时将完全失效，导致重复进行全量类型检查。这一现象在 GitHub 议题和开发者论坛中引发广泛讨论，也暴露了 mypy 缓存系统在参数敏感度设计上的潜在缺陷。
缓存失效的“现场重现”
Mypy 的缓存机制旨在加速重复检查——它会在用户项目目录下生成 .mypy_cache 文件夹，记录每个源文件的类型检查结果及依赖关系。当再次运行 mypy 时，若源文件未发生变更且依赖无改动，缓存可直接命中，跳过检查。这一机制对大型项目尤其重要，能将检查时间从数分钟缩短至数秒。
但用户在升级到 mypy 2.0 后发现如下现象：假设第一次运行 mypy src/（不带 --num-workers），缓存正常生成。随后执行 mypy src/ --num-workers 4，mypy 却完全无视已有缓存，重新扫描所有文件。更令人困惑的是，此后即使再回退到不带参数的命令，缓存依然失效——似乎 --num-workers 的存在“污染”了整个缓存状态。
根源探析：参数与缓存键的耦合
mypy 官方开发者团队在回应中指出，这一问题源于缓存键（cache key）的设计逻辑。mypy 的缓存系统会将运行时的关键参数（如 Python 版本、平台、以及部分与语义分析相关的选项）纳入缓存键计算，以确保缓存与当前运行时环境严格匹配。然而，--num-workers 参数被错误地归类为“影响缓存正确性”的关键参数。
实际上，--num-workers 仅控制并行检查的进程数量，并不改变类型检查的语义结果。无论使用单进程还是多进程，同一段代码应当得到完全一致的检查结论。但 mypy 2.0 在实现缓存键时，将 --num-workers 的数值直接作为键的一部分，导致两个仅进程数不同的调用被视为“不同环境”，缓存自然无法共享。更严重的是，当 mypy 检测到缓存键不匹配时，还会主动清空既有缓存（即使清空策略过于激进），从而触发后续调用的全量检查。
影响范围与用户反应
该问题主要影响持续集成（CI）流水线和本地开发环境。在 CI 中，开发者常根据资源情况动态调整并行数（如使用 --num-workers auto），但本地调试时可能不指定参数。每次切换都导致缓存失效，检查耗时飙升。此外，一些编辑器插件（如基于 mypy 的 VS Code 扩展）可能在后台默认使用并行模式，与用户命令行操作产生缓存冲突。
在 mypy 的 GitHub 仓库中，该议题截至发稿已获得超过 120 个 👍 表情反馈。多位用户指出，这一行为在 mypy 1.x 版本中并不存在（1.x 仅将 --num-workers 用于运行时调度，不参与缓存键生成），因此 2.0 的改动属于回归性缺陷。
官方回应与临时解决方案
mypy 核心维护者已确认该问题的严重性，并将其标记为“高优先级”（P1）。紧急修复方案正在审查中，核心思路是将 --num-workers 从缓存键计算中移除，同时改进缓存清理逻辑，避免不必要的数据清除。预计该修复将合并到 mypy 2.0.2 版本中发布。
对于等不及补丁的开发者，官方建议以下临时方案：
- 统一参数习惯：在所有调用中显式指定相同的
--num-workers值（推荐使用--num-workers 1禁用并行，或始终使用固定数值）。 - 使用环境变量锁定：通过
export MYPY_NUM_WORKERS=4使该参数全局生效。 - 手动清理缓存：在参数变更时运行
mypy --clear-cache，避免旧缓存与不匹配参数共存。 - 降级到 mypy 1.x：若项目对检查性能极其敏感，可暂时回退到 1.13 版本。
更深层的思考：缓存与参数的关系治理
此次事件并非孤例。近年来，多个 Python 工具（如 pytest、black）都曾因缓存键对配置参数过于敏感而引发问题。对于类型检查这类正确性要求极高的工作，缓存安全性与灵活性之间的平衡尤为重要。mypy 团队未来可能需要建立更完善的参数分类体系：将“影响语义”的参数（如 --strict、--python-version）与“仅影响性能”的参数（如 --num-workers、--show-error-codes）严格区分，并允许用户自定义缓存键白名单。
与此同时，开发者亦应关注工具行为变更，避免因默认参数调整导致生产力下降。正如一位 Reddit 用户所言：“缓存是现代开发体验的基石——一旦它不可靠，所有自动化都会变得昂贵。” 对于 mypy 而言，快速修正这个“小参数引发的大问题”，已是当务之急。