VSCode无法识别嵌套项目结构中src文件夹的Python导入问题

问题详情 #

• 环境：Mac Sonoma 14.0，VS Code 标准版/Insider 版本
• 项目结构：

- project/
  - sub_project_1/
    - src/
      - utils.py
    - main.py
  - ...

• 现象：在main.py中使用from src import utils时，VS Code无法识别该导入；但将src重命名为source/src2等名称后，导入恢复正常。仅当打开根目录project时出现此问题，直接打开sub_project_1则无异常。
• 已尝试：重命名src文件夹可解决问题，确认问题与src的特定命名相关。

可能原因 #

1. VS Code Python扩展特殊路径逻辑：近期扩展更新可能对src文件夹添加了默认的特殊处理规则，在多子项目的根工作区中，扩展无法正确识别子项目内的src作为模块路径。
2. 工作区配置冲突：根工作区的Python路径设置覆盖了子项目路径，导致扩展优先从根目录查找src，而非子项目内部的src。
3. 环境路径缓存：VS Code的Python扩展会缓存环境的sys.path，打开根工作区时缓存路径未包含子项目的src目录，重命名文件夹会触发路径重新扫描。
4. 工作区排除规则：可能误将src目录加入了工作区排除列表，或信任设置影响了扩展对目录的扫描。

解决方案 #

1. 手动配置子项目src路径 #

在根工作区的.vscode/settings.json中添加子项目的src路径：

{
  "python.analysis.extraPaths": [
    "${workspaceFolder}/sub_project_1/src"
  ]
}

多子项目可依次添加对应src路径。

2. 用.env文件指定模块路径 #

在sub_project_1目录下创建.env文件，添加：

PYTHONPATH=./src

VS Code Python扩展会自动读取该文件，将src加入模块查找路径。

3. 清除扩展缓存 #

• 打开命令面板（Cmd+Shift+P），执行Python: Clear Workspace Interpreter Cache。
• 重启VS Code并重新加载工作区。

4. 检查工作区排除设置 #

打开.vscode/settings.json，确认无以下配置：

{
  "files.exclude": {
    // 确保没有"sub_project_1/src": true这类规则
  },
  "search.exclude": {
    // 同上
  }
}

5. 调整Python扩展版本 #

• 打开扩展面板，找到Python扩展，点击设置图标选择Install Another Version，回滚到之前稳定版本。
• 或更新到最新版本，确认是否已修复该问题。

6. 单独打开子项目工作区 #

若无需同时处理多个子项目，直接打开sub_project_1作为工作区，避免根工作区的路径干扰。

内容的提问来源于stack exchange，提问作者NP-Complete