根本原因是PYTHONPATH未生效：pytest独立运行时不自动添加当前工作目录到sys.path，而python -m pytest会；临时sys.path.append()易因路径计算差异、环境不一致和模块污染引发问题；应通过设置PYTHONPATH环境变量或使用pip install -e .实现可靠导入。
pytest 直接运行失败，根本原因是 PYTHONPATH 没生效
当你执行 pytest test_file.py 报 ModuleNotFoundError，但 python -m pytest test_file.py 正常，不是 pytest 本身有问题，而是它没拿到你期望的模块搜索路径。Python 启动时只自动把当前工作目录（CWD）加进 sys.path 的是 python -m 这种方式；而独立安装的 pytest 命令（比如虚拟环境里的 bin/pytest）启动时不自动加 CWD——它只认 PYTHONPATH 和已安装包。
为什么不能靠 sys.path.append() 临时补救
在测试文件或 __init__.py 里写 sys.path.append(…) 看似能跑通，但实际埋了雷：
- 不同执行方式（单测文件 vs 整个
pytest目录）导致__file__路径计算结果不一致，append的路径可能错位 - IDE 运行、CI 流水线、Docker 容器里当前工作目录（CWD）很可能和你本地开发时不同，硬编码路径直接失效
- 多个测试文件各自修改
sys.path，相互污染sys.modules，出现“明明 import 成功却找不到符号”这类诡异问题
设置 PYTHONPATH 的实操要点
真正可控的方式，是在启动 pytest 前用环境变量统一注入路径：
- Linux/macOS 临时生效：
export PYTHONPATH="$(pwd):$PYTHONPATH"，再运行pytest - Windows PowerShell：
$env:PYTHONPATH = "$pwd;$env:PYTHONPATH" - 推荐值：填项目根目录（即含
src/或Library/的那个目录），不要填子目录——Python 会从该目录开始递归解析from src.module import X - 注意分隔符：Linux/macOS 用
:，Windows 用;；混用会导致整个PYTHONPATH被忽略
更可靠的长期方案：用 pip install -e . 替代 PYTHONPATH
环境变量适合调试，但上线或协作时容易漏配。真正一劳永逸的做法是让项目“变成一个可安装包”：
立即学习“Python免费学习笔记（深入）”；
- 确保项目根目录有
pyproject.toml，且project.packages正确包含你的源码目录（如["Library"]或{find = {where = ["src"]}}） - 运行
pip install -e .—— 这会把当前项目以“开发链接模式”装进 Python 环境，之后所有import Library都走标准包查找逻辑，和PYTHONPATH无关 - CI/CD 中只要加这一行安装命令，就不用再传
PYTHONPATH，也不用担心路径拼错
最易被忽略的一点：pip install -e . 后必须重启 Python 解释器进程（包括 pytest、IDE 的 Python 控制台），否则旧的 sys.path 缓存还在，新安装不会立刻生效。
