pytest采集失败时应先验证模块能否正常导入，通过python -c "import your_module"确认环境与路径问题；常见原因是sys.path缺少项目根目录或src目录，可使用pyproject.toml配置pythonpath、--import-mode=importlib或conftest.py动态添加路径解决。

pytest采集失败时如何快速定位导入错误

pytest在收集测试用例阶段（test collection）遇到ImportError或ModuleNotFoundError会直接中止，不报具体行号，只显示类似ImportError while importing test module。这不是测试执行失败，而是模块根本没加载成功——此时别急着改测试代码，先确认Python能否在当前环境下正常import你的被测模块。

最直接的验证方式是：在相同工作目录下运行python -c "import your_module"。如果这里也报错，说明问题出在环境或路径，不是pytest本身。

为什么sys.path里缺了项目根目录

pytest默认把当前执行目录（即os.getcwd()）加入sys.path[0]，但不会自动把你的包所在目录加进去。尤其当你用src/布局（如src/myapp/）、或从子目录运行pytest时，sys.path往往不含src或项目根，导致import myapp失败。

常见表现：

Secure Python Code Sandbox

安全 Python 代码沙箱：在隔离的沙箱中执行任意 Python 代码，预装 requests、NumPy、pandas 库。返回 stdout、stderr。

下载

• 在tests/目录下运行pytest，但myapp在上层目录，sys.path里没有..
• 用pytest tests/test_foo.py，但该文件里from myapp.core import X，而myapp不在sys.path中
• pip install -e .没做，又没配pyproject.toml的[build-system]，导致editable安装缺失

三种可靠解决方式（按推荐顺序）

优先选静态可复现的方式，避免依赖shell当前路径或IDE配置：

• 用pyproject.toml声明[tool.pytest.ini_options]中的pythonpath = ["src"]（若包在src/下），pytest会自动把src加到sys.path
• 运行pytest时显式指定--import-mode=importlib（Pytest 6.2+），它会用importlib.util.spec_from_file_location动态加载，绕过部分sys.path限制（但不解决import语句本身的路径问题）
• 临时加conftest.py在项目根或tests/目录下：

  import sys
  from pathlib import Path
  sys.path.insert(0, str(Path(__file__).parent.parent))

  ——注意parent.parent层级要和实际结构匹配，且只在pytest采集时生效

容易被忽略的隐性陷阱

__init__.py缺失、IDE缓存、venv激活状态不一致，都会让sys.path诊断失真。比如VS Code终端里which python和调试器用的不是同一个解释器，sys.path就不同。

真正可靠的排查动作只有两个：print(sys.path)放在conftest.py顶部，以及用python -m pytest --collect-only看采集过程是否卡在某个文件——一旦看到collected 0 items且有ImportError，说明路径没对上，别往下写断言了。

Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！