VSCode Python unittest发现失败：sys.path顺序致utils包被遮蔽

问题现象 #

多个包含utils包的Python项目中，VSCode的unittest自动发现功能失效，报错：

ModuleNotFoundError: No module named 'utils.export_to_dict_helper'; 'utils' is not a package

将项目本地的utils文件夹重命名为helper_utils后，unittest功能恢复正常；但通过终端执行python3 -m unittest discover -v tests时，即使保留utils名称也能正常运行测试。

原因分析 #

通过打印测试文件的sys.path发现：

• VSCode执行unittest发现时，会将扩展的unittestadapter目录添加到sys.path中，且该目录优先级高于工作区路径。此目录下存在utils.py文件，直接遮蔽了项目本地的utils包。
• 手动在终端运行测试时，sys.path中不存在该扩展目录，因此可以正常加载项目本地的utils包。

已尝试降级Python扩展、切换Python版本（3.8/3.11）、新建极简项目、清除__pycache__、重命名项目文件夹等操作，均无法解决问题。

解决方法 #

方法1：通过VSCode配置强制工作区路径优先 #

在项目根目录的.vscode/settings.json中添加以下配置，确保unittest从工作区根目录优先查找包：

{
  "python.testing.unittestArgs": [
    "-v",
    "-s", "./tests",
    "-p", "*test*.py",
    "--top-level-directory", "${workspaceFolder}"
  ],
  "python.analysis.extraPaths": [
    "${workspaceFolder}"
  ]
}

保存配置后，执行以下操作：

1. 按Ctrl+Shift+P打开命令面板
2. 选择Python: Restart Language Server重启语言服务
3. 重新触发unittest发现功能

方法2：在测试文件中手动调整sys.path #

如果配置调整无效，可在每个测试文件的最开头添加代码，强制将工作区根目录插入到sys.path的最前端：

import sys
from pathlib import Path

# 定位工作区根目录（假设测试文件位于tests目录下）
root_dir = Path(__file__).parent.parent
# 确保根目录在sys.path的首位
if str(root_dir) not in sys.path or sys.path.index(str(root_dir)) != 0:
    sys.path.insert(0, str(root_dir))

方法3：设置unittest工作目录 #

在.vscode/settings.json中指定unittest的工作目录为工作区根目录，进一步确保路径优先级：

{
  "python.testing.cwd": "${workspaceFolder}"
}

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