在GitHub Actions中运行pytest时出现src模块找不到的错误

问题场景 #

本地MacOS环境（Python 3.11.4）使用虚拟环境可正常运行pytest测试，但在GitHub Actions的Ubuntu环境中执行测试时，出现以下错误：

tests/test_compare.py:1: in <module>
    from src.functions.compare import imageCompare
E   ModuleNotFoundError: No module named 'src'

项目目录结构：

compliance-image-compare/
├── src/
│   └── functions/
│       └── compare.py
├── tests/
│   └── test_compare.py
├── Makefile
└── ...

已尝试在src和functions目录添加__init__.py，问题未解决。

解决方案 #

方案1：设置PYTHONPATH指向项目根目录 #

GitHub Actions环境中，Python默认不会将项目根目录加入模块搜索路径，而本地IDE通常会自动配置该路径。可以通过以下方式手动设置：

方式A：修改GitHub Actions工作流

在Run Tests步骤中添加PYTHONPATH环境变量：

- name: Run Tests
  run: |
    export PYTHONPATH=$(pwd)
    make test

方式B：修改Makefile的test目标

直接在Makefile中设置PYTHONPATH：

test:
    PYTHONPATH=. pytest tests/

方案2：将src目录安装为可编辑包 #

通过pip的可编辑安装模式，将项目根目录的src模块注册到Python环境中，这样无论在哪都能正常导入。

1. 项目根目录创建pyproject.toml（或setup.py），示例pyproject.toml内容：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "compliance-image-compare"
version = "0.1.0"
packages = ["src"]

2. 在GitHub Actions的Install Dependencies步骤后添加安装命令：

- name: Install Project in Editable Mode
  run: |
    pip install -e .

之后直接运行make test即可正常导入src模块。

为什么本地正常？ #

本地开发环境中，IDE（如PyCharm）会自动将项目根目录标记为"Source Root"，相当于自动设置了PYTHONPATH；或者你在本地虚拟环境中手动配置了路径，而GitHub Actions的全新环境没有这个配置，导致模块找不到。

内容的提问来源于stack exchange，提问作者Roni Jack Vituli