pre-commit中mypy执行成功却被判定为失败的原因排查

在macOS系统下，你使用uv run mypy作为本地pre-commit hook时触发“files were modified by this hook”错误，而改用官方mirrors-mypy就恢复正常，核心原因集中在以下几点：

• 环境隔离差异：官方mirrors-mypy hook采用pre-commit自带的隔离Python环境（language: python），会严格按照预设参数和指定版本运行mypy；而你的本地hook使用language: system，直接调用系统环境中的uv和mypy，可能继承了全局环境中你未留意的mypy配置（比如pyproject.toml或全局mypy.ini开启了fix_imports = true这类自动修复选项），导致mypy在无明确提示的情况下修改了文件内容。

• uv运行时的隐式元数据操作：在macOS文件系统下，uv run激活虚拟环境或执行命令时，可能意外修改Python文件的元数据（如访问时间、扩展属性）。虽然文件内容未发生变化，但pre-commit的文件状态检测机制对macOS的元数据变化敏感，误判为文件被修改。而官方mirrors-mypy的隔离环境规避了这类系统级的隐式操作。

• 参数配置缺失：官方mirrors-mypy hook默认传递--no-incremental等参数，禁用mypy的增量缓存功能，避免生成或修改.mypy_cache内的文件；你的本地hook未设置这类参数，若.gitignore未排除.mypy_cache，生成的缓存文件被git跟踪后，会被pre-commit判定为文件修改。

• 给本地hook添加明确参数，禁用自动修复和增量缓存：

  repos:
  - repo: local
    hooks:
    - id: mypy
      name: mypy
      language: system
      entry: uv run mypy --no-fix --no-incremental
      types: [python]
      require_serial: true
      exclude: ^(scripts/|tests/)
  

• 确保.gitignore包含.mypy_cache/和__pycache__/，避免缓存文件被git跟踪。
• 改用language: python模拟官方hook的隔离环境，通过uv管理依赖：

  repos:
  - repo: local
    hooks:
    - id: mypy
      name: mypy
      language: python
      entry: mypy
      types: [python]
      require_serial: true
      exclude: ^(scripts/|tests/)
      additional_dependencies: ["mypy"]
  

内容的提问来源于stack exchange，提问作者Seanny123