告别ModuleNotFoundError！VSCode中Python项目正确设置源码根目录的4种方法

1. 项目目录结构

TEST_ROOT
├── .env
├── .vscode
│   └── launch.json
│   └── settings.json
├── folder_A
├── folder_B
│   ├── b1
│   │   ├── __init__.py
│   │   ├── utils.py
│   ├── b2
│   │   ├── __init__.py
│   │   ├── test.py

2. 问题场景

以上目录在 VSCode 中，folder_A 和 folder_B 会被看作两个不同的工作区， VSCode 会默认将 TEST_ROOT 作为源代码根目录。此时，在 folder_B 中，b1 和 b2 中的模块无法相互导入。如果在 b2 test.py 中引用 b1 utils.py 中的常量或函数，会报错 ModuleNotFoundError: No module named 'b1'。

3. Pycharm 解决方案

众所周知，在 Pycharm 中，只需要在 folder_B 上右键，选择 Mark Directory as -> Sources Root 即可，非常方便。

4. VSCode 解决方案

但是在 VSCode 中，并没有如此快捷方便的操作，搜索资料后都提示需要手动修改配置文件。于是，尝试了以下解决方案，特此记录。

4.1（方案一）修改项目配置文件【失败】

在根目录 TEST_ROOT 下 .vscode/settings.json 文件中添加如下配置：

{
  "python.pythonPath": "python",
  "python.autoComplete.extraPaths": ["${workspaceFolder}/folder_B"],
  "python.analysis.extraPaths": ["${workspaceFolder}/folder_B"],
  "python.analysis.autoSearchPaths": true
}

配置解释

• "python.pythonPath"：指定 Python 解释器的路径。
• "python.autoComplete.extraPaths"：指定自动补全时搜索的路径。
• "python.analysis.extraPaths"：指定静态分析时搜索的路径。
• "python.analysis.autoSearchPaths"：自动搜索路径。

4.2（方案二）修改项目启动配置文件【失败】

在根目录 TEST_ROOT 下 .vscode/launch.json 文件中添加如下配置：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python 调试程序: 当前文件",
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "cwd": "${workspaceFolder}/folder_B" // 添加此行
    }
  ]
}

配置解释

• "cwd"：指定工作区根目录。

4.3（方案三）修改项目环境配置文件【成功】

在根目录 TEST_ROOT 下 .env 文件中添加如下配置：

PYTHONPATH=/root/test_root/folder_B

添加后，重启 VSCode，问题解决。

配置解释

• "PYTHONPATH"：指定 Python 解释器的路径。（此处添加 folder_B 的绝对路径）

注意，后续测试发现：

• 使用 conda 的虚拟解释器，该方案没问题
• 使用系统解释器（比如 /bin/python3 或者 /usr/bin/python3 ），仍然无法解决该问题

4.4（方案四）修改项目配置文件【成功】【推荐】

在根目录 TEST_ROOT 下 .vscode/settings.json 文件中添加如下配置：

{
  "terminal.integrated.env.linux": {
    "PYTHONPATH": "${workspaceFolder}/folder_B:${env:PYTHONPATH}"
  }
}

配置解释

• "terminal.integrated.env.linux.PYTHONPATH"：指定 Python 解释器的路径。

5. 其他方案

在系统中直接修改 PYTHONPATH 环境变量，但这种方式并不推荐，因为

1. VSCode 的 .env 文件优先级更高。
2. 修改系统环境变量会影响其他项目。

6. 结论

在 VSCode 中，修改 .env 文件是解决源代码根目录问题的最佳方案。
在 VSCode 中，修改 .vscode/settings.json 文件中 "terminal.integrated.env.linux.PYTHONPATH" (即4.4（方案四）修改项目配置文件【成功】【推荐】)是解决源代码根目录问题的最佳方案。