pre-commit执行mypy钩子报错：setuptools无CompileError属性

云上老周

2026-7-27

解决pre-commit mypy钩子报"setuptools._distutils.errors无CompileError"的问题

以下是几个可行的排查和解决步骤：

补充setuptools的类型定义
mypy默认可能未包含setuptools的完整类型信息，你可以给pre-commit的mypy钩子添加types-setuptools依赖。修改仓库的.pre-commit-config.yaml：
```
- repo: https://github.com/pre-commit/mirrors-mypy
  rev: v1.5.1  # 替换为你使用的mypy版本
  hooks:
    - id: mypy
      additional_dependencies: [types-setuptools]
```
执行pre-commit clean && pre-commit install --install-hooks重新安装钩子。
检查mypy加载的setuptools路径
激活pre-commit的mypy虚拟环境后，运行mypy --show-traceback /path/to/file.py，查看输出中setuptools模块的加载路径，确认是否误加载了项目本地的旧版本setuptools。如果是，可临时移除项目本地的setuptools（之后再重新安装），或者在mypy配置中排除项目的site-packages目录。
替换内部模块导入为公开API
setuptools._distutils是私有内部模块，兼容性无保障。把代码中的from setuptools._distutils.errors import CompileError替换为from distutils.errors import CompileError——setuptools会自动patch公开的distutils模块，这样既兼容旧版本，也能让mypy正确识别类型。
强制指定钩子的setuptools版本
在mypy钩子的额外依赖中明确指定setuptools版本，避免pre-commit自动安装时出现版本偏差：
```
- repo: https://github.com/pre-commit/mirrors-mypy
  rev: v1.5.1
  hooks:
    - id: mypy
      additional_dependencies: [setuptools>=67.6.0, types-setuptools]
```
清理缓存后重新安装钩子。