在GitHub Actions工作流中Pylint无法识别src模块的问题

问题重现 #

在GitHub Actions工作流中执行pylint src时出现致命错误：

Run pylint src
  pylint src
  shell: /usr/bin/bash -e {0}
  env:
    pythonLocation: /opt/hostedtoolcache/Python/3.10.9/x64
    LD_LIBRARY_PATH: /opt/hostedtoolcache/Python/3.10.9/x64/lib
************* Module src
src:1:0: F0001: No module named src (fatal)
Error: Process completed with exit code 1.

但本地项目根目录运行相同命令完全正常：

(base) bob@Roberts-Mac-mini myproject % pylint src

--------------------------------------------------------------------
Your code has been rated at 10.00/10 (previous run: 10.00/10, +0.00)

核心问题分析 #

• 缺少代码拉取步骤：当前GitHub Actions工作流未配置代码拉取逻辑，导致运行pylint时工作目录下不存在src目录，无法识别模块。
• Python路径差异：本地环境会自动将当前工作目录加入Python的sys.path，但CI环境中可能未默认添加，导致pylint无法将src识别为合法模块。

修复方案 #

步骤1：添加代码拉取步骤 #

在Set up Python步骤前加入仓库代码拉取逻辑，确保工作目录存在项目文件：

- name: Checkout repository
  uses: actions/checkout@v4

步骤2：确保项目根目录加入Python路径 #

以下两种方式二选一即可：

方式一：设置PYTHONPATH环境变量

在pylint运行前手动将当前工作目录加入Python路径：

- name: Lint with pylint
  run: |
    export PYTHONPATH="$PWD"
    pylint src
  continue-on-error: false

方式二：安装项目为可编辑模式

在依赖安装步骤末尾添加项目可编辑安装命令，自动将根目录加入sys.path：

- name: Install dependencies
  run: |
    python -m pip install --upgrade pip
    pip install pylint pytest pytest-cov
    if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
    pip install -e .

完整修复后的工作流配置 #

name: Python application

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

permissions:
  contents: read

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - name: Checkout repository
      uses: actions/checkout@v4
    - name: Set up Python 3.10
      uses: actions/setup-python@v3
      with:
        python-version: "3.10"
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install pylint pytest pytest-cov
        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
        pip install -e .
    - name: Lint with pylint
      run: |
        pylint src
      continue-on-error: false
    - name: Test with pytest
      run: |
        pytest
    - name: pytest coverage
      run: |
        pytest --cov=./ --cov-report=xml:tests/coverage.xml
    - name: Upload coverage to Codecov
      uses: codecov/codecov-action@v3

验证说明 #

完成上述修改后，GitHub Actions会先拉取项目代码，再确保Python能正确识别src模块，pylint检查即可正常运行，与本地行为保持一致。

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