VS Code中Debug Test报错ModuleNotFoundError，如何配置路径？

问题症状 #

通过VS Code测试侧边栏或测试方法右键菜单的Debug Test功能调试单元测试时，调试控制台出现模块找不到错误：

E
======================================================================
ERROR: test_clients (unittest.loader._FailedTest)
----------------------------------------------------------------------
ImportError: Failed to import test module: test_clients
Traceback (most recent call last):
  File "/usr/lib/python3.8/unittest/loader.py", line 154, in loadTestsFromName
    module = __import__(module_name)
  File "/home/melebius/git/my-project/my_project/tests/test_clients.py", line 9, in <module>
    from my_project.clients.base import Data
ModuleNotFoundError: No module named 'my_project'


----------------------------------------------------------------------
Ran 1 test in 0.007s

FAILED (errors=1)

my_project目录未被Python解释器识别，但Run Test功能、项目根目录下的python -m unittest命令均可正常运行测试。

已尝试方案 #

• 在测试文件中临时追加路径，仅能临时解决问题，无法提交到Git
• 在.code-workspace文件中配置PYTHONPATH，普通调试（非unittest）可正常运行，但Debug Test无效果
• 在项目.env文件中定义PYTHONPATH，无效果
• 工作区和项目级launch.json均已设置PYTHONPATH，无效果

补充信息 #

• 使用Microsoft Python和Pylance扩展提供测试环境
• 项目采用venv虚拟环境，依赖已正确安装
• 工作区包含多项目，结构如下：

.
 |-my-project
 | |-my_project
 | | |-tests
 | | |-clients
 | | |-tools
 | |-.git
 | |-.vscode
 | | |-launch.json
 |-my-other-project
 | |-.git
 | |-...
 |-my-yet-another-project
 | |-.git
 | |-...
 |-my-projects.code-workspace

解决方案 #

VS Code的Debug Test功能不使用launch.json的配置，而是依赖python.testing相关设置，以下是可行的配置方法：

方法1：指定测试工作目录 #

在my-project/.vscode/settings.json中添加配置，将Debug Test的工作目录设为项目根目录：

{
  "python.testing.cwd": "${workspaceFolder}/my-project"
}

此配置让Debug Test的执行环境与你在项目根目录运行python -m unittest一致，Python会自动识别my_project模块。

方法2：通过环境文件加载PYTHONPATH #

确保项目根目录的.env文件已添加：

PYTHONPATH=/home/melebius/git/my-project

然后在my-project/.vscode/settings.json中指定加载该环境文件：

{
  "python.envFile": "${workspaceFolder}/my-project/.env"
}

Debug Test会读取该环境文件，从而设置正确的模块搜索路径。

方法3：调整unittest测试参数 #

若上述方法无效，可在my-project/.vscode/settings.json中配置unittest的顶层目录参数：

{
  "python.testing.unittestArgs": [
    "-v",
    "-s", "./my_project/tests",
    "-p", "test_*.py",
    "--top-level-directory", "${workspaceFolder}/my-project"
  ]
}

--top-level-directory参数会告知unittest项目的根位置，帮助它定位到my_project模块。

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