【Python】VSCode：解决模块导入与调试

使用场景

在 VSCode 中使用 Python 插件时，经常会遇到以下问题：

• 在项目结构中运行子模块脚本时报错：ModuleNotFoundError
• 点击“运行按钮”或使用“调试”功能时找不到自定义模块
• 希望不修改源代码、不依赖 .env 文件的前提下解决导入路径问题

这是因为 VSCode 默认的工作目录不一定是项目根目录，导致 sys.path 中缺少你定义模块的路径。

---

配置 launch.json

我们可以通过 VSCode 的调试配置文件 launch.json 显式设置环境变量 PYTHONPATH，将项目根目录加入 Python 模块搜索路径。

1. 在项目根目录下新建或打开 .vscode/launch.json。
2. 添加以下内容：

{"version": "0.2.0","configurations": [{"name": "Python: 当前文件（PYTHONPATH）","type": "debugpy","request": "launch","program": "${file}","console": "integratedTerminal","env": {"PYTHONPATH": "${workspaceFolder}"  // 关键：加入项目根目录}}]
}

---

使用方法

1. 在 VSCode 左侧点击【运行与调试】图标（或按 Ctrl+Shift+D）。

2. 在顶部下拉菜单中选择：

   Python: 当前文件（PYTHONPATH）
   

3. 点击绿色的 ▶️ 或按 F5 开始调试。

---

效果验证

运行如下代码：

# test.py
from utils.tools import hello
hello()

只要 utils/ 文件夹在项目根目录下，不论你在哪个子模块运行 test.py，都能正确导入 utils.tools 模块。