在Python项目中使用Pytest跑测试时，模块导入错误是最常见的问题之一。根本原因在于解释器运行时sys.path里没有包含被测代码所在的目录。Pytest有一套自己的导入策略，但如果项目布局复杂，仍然需要手动或约定式地管理sys.path。
为什么Pytest会出现导入问题
Pytest默认使用rootdir和test文件的位置来决定如何导入模块。当测试用例里写import myapp而myapp不在sys.path中时，就会抛出ModuleNotFoundError。特别是在使用src布局或者多层包结构时，更容易踩坑。
利用conftest.py管理路径
conftest.py是Pytest的本地插件文件，它所在的目录会被自动加入sys.path。我们可以在项目的根conftest.py里手动把源码目录插到最前面。
import os
import sys
# 将项目根目录加入sys.path，确保导入稳定
root_path = os.path.dirname(os.path.abspath(__file__))
src_path = os.path.join(root_path, "src")
if src_path not in sys.path:
sys.path.insert(0, src_path)
使用pytest.ini标记根目录
通过配置pytest.ini，可以明确告诉Pytest哪里是根目录，配合合理的包结构减少路径烦恼。
[pytest] rootdir = . python_files = test_*.py
常见项目结构示例
| 结构类型 | 说明 |
|---|---|
| 平铺结构 | 测试和源码在同一级，简单但易混乱 |
| src布局 | 源码放src下，测试放tests，推荐做法 |
手动插入路径的注意事项
- 尽量在conftest.py中统一处理，不要在每个测试文件里写sys.path操作
- 插入路径优先用sys.path.insert(0, path)保证优先级
- 避免把相对路径直接加入，应使用绝对路径
良好的sys.path管理能让Pytest在不同机器和CI环境里表现一致，是可靠测试的基础。
小结
掌握sys.path和Pytest导入机制的关系，使用conftest.py统一注入路径、规范项目布局，就能彻底解决大部分导入报错。写测试前先理清目录结构，比报错后再补路径要轻松得多。