跟随TestDriven.io FastAPI Docker教程运行pytest出现导入不匹配错误求助

1. 确认项目目录结构合规 #

该问题90%的诱因是目录结构不符合Python包识别规则，先对照标准结构核查：

• 项目根目录
  • docker-compose.yml
  • app/
    • __init__.py（必须存在，Python才会将该文件夹识别为可导入的包）
    • main.py
    • config.py
    • tests/
      • __init__.py
      • conftest.py（如果conftest.py放在项目根目录而非app/tests目录下，必然出现导入错误）

2. PyCharm导入提示错误修复 #

如果目录结构正确但PyCharm仍标红导入语句：

• 右键点击app文件夹的上级目录（即项目根目录）
• 选择「Mark Directory as」→ 「Sources Root」，PyCharm会自动适配导入路径规则。

3. Docker环境pytest运行报错修复 #

目录结构正确的前提下容器内运行测试仍报错，按以下步骤排查：

• 核查docker-compose.yml中web服务的路径配置，确保本地app目录正确挂载到容器工作目录下，参考配置片段：

services:
  web:
    build: ./project
    working_dir: /usr/src/app
    volumes:
      - ./project:/usr/src/app

• 新增路径识别规则：可以直接修改运行命令指定Python路径
  docker-compose exec web python -m PYTHONPATH=. pytest
  或者在项目根目录新增pytest.ini文件添加固定配置：

[pytest]
pythonpath = .
testpaths = app/tests

4. 路径问题排查方案 #

如果以上操作都无效，可以在conftest.py顶部添加代码确认路径：

import sys
print(sys.path)

运行pytest后查看输出的路径列表是否包含app文件夹的上级目录，如果没有则手动在conftest.py最顶部添加路径声明：

import sys
from pathlib import Path
# 按你实际的conftest存放位置调整.parent层级，确保最终指向app文件夹的上级目录
sys.path.append(str(Path(__file__).parent.parent.parent))

内容的提问来源于stack exchange，提问作者spetz83