如何配置VSCode调试时查找同命名空间虚拟环境中的依赖模块

核心原因 #

你的companyA是常规包（存在__init__.py）而非命名空间包，Python调试时会优先使用本地src/companyA目录，不会合并虚拟环境site-packages中同命名空间的模块；同时本地src目录被优先加入sys.path，导致虚拟环境中的companyA.moduleA未被检索。

解决方案 #

1. 将companyA改为命名空间包（推荐） #

Python 3.3+支持无__init__.py的命名空间包，不同位置的同命名空间目录会被自动合并，无需额外配置即可跨路径查找子模块：

• 删除moduleA和moduleB中companyA目录下的__init__.py文件；
• 若需兼容Python 3.3之前版本，可在companyA/__init__.py中添加以下代码：

  from pkgutil import extend_path
  __path__ = extend_path(__path__, __name__)
  

2. 调整VSCode调试配置的PYTHONPATH #

如果不想修改包结构，可通过调试配置强制让Python优先检索虚拟环境的site-packages，同时保留本地src路径：

1. 打开VSCode的调试面板，点击齿轮图标打开launch.json；
2. 添加或修改调试配置，在env中配置PYTHONPATH，将虚拟环境的site-packages路径放在前面：

   {
       "version": "0.2.0",
       "configurations": [
           {
               "name": "Debug ModuleB",
               "type": "python",
               "request": "launch",
               "program": "${file}",
               "env": {
                   "PYTHONPATH": "${python.pythonPath}/../lib/python3.11/site-packages:${workspaceFolder}/src:${env:PYTHONPATH}"
               },
               "justMyCode": false
           }
       ]
   }
   

   • ${python.pythonPath}会自动指向当前选中的虚拟环境解释器路径，替换python3.11为你的实际Python版本号。

3. 手动调整代码中的sys.path #

在moduleB的入口文件开头添加以下代码，强制将虚拟环境site-packages路径加入sys.path的优先级位置：

import sys
from pathlib import Path

# 定位虚拟环境的site-packages目录
venv_site_packages = next(p for p in sys.path if "site-packages" in p)
# 将其插入到sys.path的最前面，确保优先检索
sys.path.insert(0, venv_site_packages)

验证步骤 #

1. 确认VSCode已选中build文件夹下的虚拟环境作为当前解释器；
2. 按照上述任一方案配置后，重新启动调试，检查companyA.moduleA是否能正常导入。

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