如何在 VSCode 中配置 Python 调试环境避免 No module named 错误？

VSCode 调试 Python 时遇到 No module named xxx，最常见的原因是调试器使用的 Python 解释器与项目实际安装模块的解释器不一致，或者工作区根目录未正确加入模块搜索路径。下面按排查优先级给出处理路径，每一步都附带确认方法。

先检查这两个地方，别急着改配置

遇到模块缺失错误，不要立刻去改 launch.json。先确认两件事：

当前激活的 Python 解释器：在 VSCode 左下角状态栏可以看到当前解释器路径，点击可以切换。如果这里显示的路径不是虚拟环境中的 python，调试时很可能找不到已安装的包。
终端里能否正常导入该模块：在 VSCode 内置终端中激活对应虚拟环境，执行 python -c "import xxx"。如果终端能成功，但调试报错，说明调试器使用了不同的解释器；如果终端也报错，说明模块确实没装对环境。

先解决终端导入问题：确保在正确的虚拟环境下 pip install xxx。如果项目使用 requirements.txt 或 Pipfile，优先用对应工具安装。

.vscode/launch.json 里的 pythonPath 与模块路径写法

调试配置中 pythonPath 字段直接指定调试器使用的 Python 可执行文件路径。如果项目使用了虚拟环境，建议写成绝对路径或使用 ${workspaceFolder} 变量。例如：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "pythonPath": "${workspaceFolder}/venv/bin/python"
        }
    ]
}

注意：pythonPath 在较新版本 VSCode Python 扩展中已被 python 设置覆盖。更推荐在 settings.json 中指定 python.defaultInterpreterPath，并在 launch.json 中省略 pythonPath，让调试器自动使用默认解释器。如果模块位于项目子目录中，需要在 env 或 cwd 中调整 PYTHONPATH。例如：

"env": {
    "PYTHONPATH": "${workspaceFolder}/src"
}

这种方式只影响调试会话，不影响终端或其他工具。

虚拟环境激活与终端环境一致性

很多团队使用 conda 或 venv 管理环境，但 VSCode 的 Python 扩展默认会从 setting.json 中读取解释器路径。如果这个路径写死了全局 Python，而项目实际依赖虚拟环境中的包，就会出现模块缺失。建议在项目根目录的 .vscode/settings.json 中设置：

{
    "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python"
}

如果使用 conda，路径类似 ${workspaceFolder}/envs/myenv/bin/python。设置后重启 VSCode，状态栏的解释器会对应更新。还有一种隐蔽情况：调试时启动的终端继承的是 VSCode 默认 shell 的环境变量，如果 .bashrc 或 .zshrc 中有 conda init 自动激活基础环境，会导致调试器与手动激活的环境冲突。建议在 launch.json 中明确指定 "console": "integratedTerminal" 并先验证终端环境，或者使用 "console": "internalConsole" 避免终端干扰。

工作区根目录与 sys.path 的关系

Python 在寻找模块时，会将当前脚本所在目录（或启动目录）加入 sys.path。如果项目结构是 project/src/module.py，而调试入口在 project/main.py，且 main.py 中 import src.module，那么在 launch.json 中需要设置 "cwd": "${workspaceFolder}"，使得工作目录为项目根目录。否则，当 cwd 指向 project/src 时，import module 可以，但 import src.module 会失败。检查方法：在调试开始后，在调试控制台执行 import sys; print(sys.path)，确认是否包含期望的搜索路径。如果缺少，可以在 launch.json 的 env 中添加 "PYTHONPATH": "${workspaceFolder}"。

改完后看这几个信号

修改配置后，不需要重启 VSCode，只需重新启动调试（按 F5）。观察以下信号：

左下角解释器路径：是否显示为你指定的虚拟环境路径。
调试控制台输出的 Python 版本和路径：在调试输出中会打印 Python 解释器位置，确认与实际一致。
终端中执行 pip list：确认模块已列出。如果模块名带下划线或连字符，注意大小写。
尝试在代码开头加 import sys; print(sys.path)：立即输出搜索路径，方便定位。

如果问题依旧，考虑清除 VSCode Python 扩展缓存：Ctrl+Shift+P 输入 Python: Clear Cache and Reload Window。这个操作会让扩展重新扫描环境和路径。

回滚边界：改错了怎么还原

所有修改都在项目目录下的 .vscode/ 文件夹中。如果改乱，可以删除整个 .vscode/ 目录（不影响项目源文件），VSCode 会重新使用全局设置和默认解释器。或者使用版本管理工具（如 Git）撤销对 .vscode/ 中文件的更改。注意：.vscode/settings.json 中的 python.defaultInterpreterPath 如果写错路径，VSCode 会提示找不到解释器，此时回退为空字符串即可让扩展自动选择。不要同时修改全局 settings.json 和项目 settings.json，优先使用项目级配置，避免影响其他项目。