unittest VSCode运行正常但CLI执行报ModuleNotFoundError解决方法

问题根因 #

VSCode和CLI运行测试时的Python模块搜索路径（sys.path）规则不一致：

• VSCode测试插件默认自动将当前打开的项目根目录加入模块搜索路径，所有从根目录起始的导入均可正常识别
• CLI执行unittest时，默认仅将当前执行命令的工作目录、测试脚本所在目录加入搜索路径，若路径未覆盖项目根目录，或代码存在依赖根路径的导入，就会抛出模块找不到的错误。

从报错信息和贴出的代码看，存在两个显性问题：

1. 导入代码存在拼写错误：from scr.external import db中scr应为src，from src.exerternal import info_email中exerternal应为external
2. 核心报错来自src/external/db/__init__.py中的import configuration语句：该语句默认依赖项目根目录在搜索路径内（即configuration包/模块存放在项目根目录下），CLI执行时未加载根目录路径导致识别失败。

解决方案 #

优先选第一种方案，改造成本最低，最适配流水线执行场景。

方案1：固定执行目录+配置PYTHONPATH（推荐流水线使用） #

先确认项目目录符合如下标准结构：

项目根目录/
├── configuration/  # 报错缺失的configuration模块存放位置
├── src/
│   ├── external/
│   │   └── db/
│   │       └── __init__.py
│   └── test/
│       └── test.py

执行测试前先切换到项目根目录，手动将项目根目录加入PYTHONPATH环境变量，再用模块模式启动unittest：

• Windows CMD环境：

cd C:\Users\raul_gomes\Documents\repos\autopilotdaocsgorderservices
set PYTHONPATH=.
python -m unittest discover -s src/test -p "test*.py"

• Windows PowerShell环境：

cd C:\Users\raul_gomes\Documents\repos\autopilotdaocsgorderservices
$env:PYTHONPATH="."
python -m unittest discover -s src/test -p "test*.py"

• Linux/Mac/CI流水线环境：

cd /path/to/project/root
export PYTHONPATH=.
python -m unittest discover -s src/test -p "test*.py"

注意：必须使用python -m unittest的方式执行，不要直接运行python src/test/test.py，后者会将测试文件所在目录作为执行根目录，依然会出现模块找不到的问题

方案2：修正不规范导入语句 #

将代码中依赖搜索路径的硬导入改成规范的绝对导入/相对导入，从根源上消除路径依赖：

• 如果configuration是项目根目录下的公共模块，统一使用从根路径起始的绝对导入
• 如果configuration和导入它的db模块存在层级关系，使用相对导入，例如configuration在src/external目录下时，将import configuration改为from .. import configuration

方案3：测试入口手动注入搜索路径（仅本地临时调试用） #

在测试文件最顶部、所有业务模块导入之前，手动将项目根目录加入sys.path，示例：

import sys
import os
# 计算项目根目录路径，加入模块搜索列表
PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
sys.path.append(PROJECT_ROOT)

# 后续再写业务导入逻辑
from src.external import db
from src.external import info_email

该方案需要在每个测试文件添加重复逻辑，维护成本高，不推荐流水线场景使用。

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