Python单元测试中模块导入失败是开发过程中非常常见的问题，尤其是在使用Pytest框架运行测试用例时，不同目录层级的模块引用很容易出现找不到模块的错误，这类问题大多和项目结构设置、Python路径配置有关。
常见的模块导入失败场景
我们先来看一个典型的项目结构，很多新手开发者的项目会这样组织：
my_project/
├── src/
│ ├── utils.py
│ └── main.py
└── tests/
└── test_main.py
当在test_main.py中尝试导入src目录下的模块时，很容易出现ModuleNotFoundError的错误，比如执行以下导入语句：
# tests/test_main.py from src.main import func # 执行时大概率会报错找不到模块
出现这类问题的核心原因是，Pytest执行测试时的当前工作目录和Python的sys.path路径配置不匹配，导致解释器找不到对应层级的模块。
Pytest的模块导入机制
Pytest在执行测试时，会将被测试文件所在的目录添加到sys.path中，同时也会将执行Pytest命令的当前工作目录添加到sys.path。如果项目结构没有做适配，就会出现路径找不到的情况。
我们可以通过一段简单的代码查看当前Pytest执行时的路径配置：
# tests/test_path.py
import sys
def test_sys_path():
# 打印当前Python解释器的搜索路径
for path in sys.path:
print(path)
执行pytest tests/test_path.py -s之后，就能看到所有路径的打印结果，从中可以确认目标模块所在的目录是否在搜索路径中。
项目结构优化方案
方案一：使用setup.py或pyproject.toml安装项目
最规范的方式是将项目作为可安装的包，这样无论在哪里执行测试，模块都能被正确导入。我们可以在根目录创建pyproject.toml文件：
# pyproject.toml [build-system] requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" [project] name = "my_project" version = "0.1.0" [tool.setuptools.packages.find] where = ["src"]
然后在项目根目录执行安装命令：
pip install -e .
安装完成后，就可以在测试文件中正常导入src下的模块了：
# tests/test_main.py
from main import func # 此时可以正常导入，因为项目已经被安装到Python环境中
def test_func():
assert func() == "expected_result"
方案二：配置Pytest的pythonpath
如果不想安装项目，也可以通过配置Pytest的pythonpath来添加模块搜索路径。在项目根目录创建pytest.ini文件：
# pytest.ini [pytest] pythonpath = .
这样Pytest执行时会把项目根目录添加到sys.path中，测试文件中就可以用相对路径导入模块：
# tests/test_main.py
from src.main import func
def test_func():
assert func() is not None
方案三：在测试代码中动态添加路径
如果是临时调试，也可以在测试文件开头动态添加模块所在路径，这种方式不推荐长期使用，只适合临时验证：
# tests/test_main.py
import sys
import os
# 获取当前文件所在目录的父目录，也就是项目根目录
sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
from src.main import func
def test_func():
assert func() == "test"
不同方案的选择建议
我们可以通过下面的表格对比不同方案的适用场景：
| 方案 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|
| 安装项目为包 | 正式开发、团队协作项目 | 符合Python包规范，导入稳定，不会出现路径问题 | 需要配置包文件，步骤稍多 |
| 配置pytest.ini的pythonpath | 小型个人项目、快速调试 | 配置简单，无需安装项目 | 依赖配置文件，换环境需要重新配置 |
| 动态添加路径 | 临时测试、快速验证 | 无需额外配置，改代码即可生效 | 代码侵入性强，不适合长期维护 |
注意事项
- 不要在测试文件中使用
__import__等动态导入方式，会增加代码维护难度 - 目录命名不要和Python标准库模块重名，比如不要把自己的目录命名为
test、json等，避免导入冲突 - 如果使用了相对导入，要确保模块是包的一部分，也就是目录下有
__init__.py文件（Python 3.3+的命名空间包可以没有，但正式项目建议加上）
通过以上几种方式，基本可以解决绝大多数Python单元测试中Pytest的模块导入失败问题，开发者可以根据项目的实际情况选择合适的方案。