使用场景

在 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 模块。