如何在VS Code中调试Python unittest并解决模块导入报错

报错由两个核心问题共同导致：

1. 自定义包命名冲突：你创建的code包和Python标准库内置的code模块重名，当本地包路径不在搜索路径最高优先级时，Python会直接加载标准库的code模块，自然找不到其下的car子模块。
2. VS Code模块搜索路径和命令行不一致：你在项目根目录执行命令行测试时，当前工作目录（项目根）会被加入模块搜索路径最高优先级，本地code包会被优先命中；但VS Code默认不会自动把项目根目录加入搜索路径，打开子目录文件启动调试时，会优先把当前文件所在目录（比如tests文件夹）加入搜索路径，触发上述重名冲突。

1. 一劳永逸解决命名冲突 #

将根目录下的code文件夹重命名为和标准库不冲突的名称，比如car_core、project_code均可，同步修改所有文件中的导入语句：

• 测试文件、主代码中所有import code.xxx、from code import xxx的写法，全部替换为新包名对应的导入路径
• 只要包名和标准库重名，后续不管怎么调整路径，都有概率触发诡异的导入问题，这一步是最稳妥的修复。

2. 修正VS Code配置，统一模块搜索路径 #

修改launch.json调试配置 #

你当前的配置存在两个问题：一是Python: Module配置指定的main模块在你的项目结构中不存在，二是没有显式指定项目根目录为模块搜索根路径。修改为如下配置：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Debug Tests",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "purpose": ["debug-test"],
            "console": "integratedTerminal",
            "justMyCode": false,
            "env": {
                "PYTHONPATH": "${workspaceFolder}"
            }
        },
        {
            "name": "Python: Run Main Entry",
            "type": "python",
            "request": "launch",
            // 替换为你实际的入口文件路径，比如入口为根目录下main.py则保持下述写法
            "program": "${workspaceFolder}/main.py",
            "justMyCode": false,
            "cwd": "${workspaceFolder}",
            "env": {
                "PYTHONPATH": "${workspaceFolder}"
            }
        }
    ]
}

核心改动是通过env字段给两个调试配置都添加了PYTHONPATH环境变量，强制把项目根目录加入Python模块搜索路径，和你命令行执行时的路径逻辑保持一致。

修正测试配置 #

在原有测试配置基础上添加环境变量配置，保证测试进程也能正确找到项目根路径：

{
    "python.testing.unittestArgs": [
        "-v",
        "-s",
        "./tests",
        "-p",
        "test_*.py"
    ],
    "python.testing.pytestEnabled": false,
    "python.testing.unittestEnabled": true,
    "python.testing.cwd": "${workspaceFolder}",
    "python.testing.env": {
        "PYTHONPATH": "${workspaceFolder}"
    }
}

注意调试测试时，优先通过VS Code测试面板的「调试测试」按钮启动，不要直接打开测试文件选普通调试配置启动。

Python导入模块时会按照sys.path列表的顺序从前往后搜索路径，VS Code启动Python进程时，sys.path的生成优先级如下：

1. 被执行的脚本文件所在的目录，优先级最高
2. 启动配置中cwd字段指定的工作目录
3. 系统环境变量PYTHONPATH中配置的所有路径
4. Python安装目录下的标准库路径、第三方库site-packages路径

VS Code默认不会自动将工作区根目录加入PYTHONPATH，如果打开子目录下的文件启动调试，最高优先级的搜索路径会变成子目录路径，很容易出现本地包找不到、命中同名标准库/第三方库的问题。遇到导入问题时，可以在报错文件开头添加如下代码打印sys.path，快速定位路径配置问题：

import sys
for p in sys.path:
    print(p)

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