pre-commit在Push时触发Pylint错误，本地执行无异常的问题排查

pre-commit配置文件 #

repos:
- hooks:
  - args:
    - -rn
    - -sn
    - --rcfile=.pylintrc
    entry: poetry run pylint
    id: pylint
    language: system
    stages:
      - pre-commit
      - pre-push
    name: pylint
    types:
    - python
  repo: local
- hooks:
  - id: commitizen
  - id: commitizen-branch
    stages:
    - push
  repo: https://github.com/commitizen-tools/commitizen
  rev: v3.10.0

报错信息 #

执行Push操作时，pylint钩子报错：

pylint...................................................................Failed
- hook id: pylint
- exit code: 2

************* Module account.auth.models.user
account\auth\models\user.py:17:0: E0611: No name 'mixins' in module 'painless.models' (no-name-in-module)

异常现象 #

• pre-commit阶段执行无异常
• 执行pre-commit run -a时无任何错误
• 直接执行pylint ./**会在其他文件出现新错误

项目文件结构 #

user.py
painless/
├── __init__.py
└── models/
    └── __init__.py/
        └── mixins/
            ├── __init__.py
            └── common.py

注：user.py中导入语句为from painless.models.mixins import TimeStampMixin，且painless/models/mixins/__init__.py已正确导出TimeStampMixin类：from .common import TimeStampMixin

为什么pre-commit与pre-push阶段行为不一致？ #

1. 检查范围差异：pre-commit钩子默认仅检查暂存区的修改文件，如果user.py在pre-commit通过后未再修改，钩子不会重复检查；但pre-push钩子会触发检查所有匹配types: python的文件，此时pylint的处理环境可能和pre-commit不同。
2. Python路径（sys.path）差异：pre-commit在运行不同阶段的钩子时，可能会调整工作目录或sys.path，导致pre-push时pylint无法找到painless.models.mixins模块。比如钩子运行时的工作目录不是项目根目录，就会导致模块导入失败。
3. pylint缓存干扰：pylint会缓存检查结果，pre-commit可能复用了缓存结果，而pre-push时缓存失效，导致暴露之前未发现的导入问题。

如何复现错误？ #

1. 直接模拟pre-push阶段的钩子运行：

   pre-commit run pylint --hook-stage=pre-push
   

   该命令会完全复刻push时的钩子执行逻辑，大概率能复现报错。
2. 对比不同场景下的Python路径：在user.py开头临时添加以下代码，分别在pre-push钩子和pre-commit run -a中运行，查看输出的sys.path差异：

   import sys
   print("Current sys.path:", sys.path)
   

修复方案 #

1. 强制添加项目根目录到Python路径
   修改pylint钩子的参数，添加--init-hook来确保项目根目录被加入sys.path，配置如下：

   - hooks:
     - args:
       - -rn
       - -sn
       - --rcfile=.pylintrc
       - --init-hook="import sys; sys.path.insert(0, '.')"
       entry: poetry run pylint
       id: pylint
       language: system
       stages:
         - pre-commit
         - pre-push
       name: pylint
       types:
       - python
     repo: local
   

2. 修正项目结构笔误
   你提供的结构中painless/models/__init__.py/是目录（带斜杠），这会导致Python无法识别painless.models为合法模块。需确保painless/models/下是__init__.py文件，而非目录，正确结构应为：

   user.py
   painless/
   ├── __init__.py
   └── models/
       ├── __init__.py
       └── mixins/
           ├── __init__.py
           └── common.py
   

3. 清除pylint缓存
   运行以下命令清除缓存，避免缓存导致的结果不一致：

   pylint --clear-cache
   

4. 统一钩子检查范围（可选）
   如果希望pre-commit和pre-push检查范围完全一致，可在pylint钩子中添加always_run: true，或设置files: .*指定检查所有Python文件，但会增加pre-commit的检查耗时。

是否是Pylint本身的问题？ #

不是Pylint本身的问题，核心原因是pre-commit不同阶段的运行环境差异（路径、检查范围），以及项目结构可能存在的笔误导致模块识别失败。

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