如何在VSCode中配置Python复合命名空间包？

核心配置修正 #

• 正确设置PYTHONPATH：不要添加core/python/common，而是将core/python加入PYTHONPATH。Python解释器需要的是命名空间包的父级目录，这样才能识别common作为无__init__.py的复合命名空间包。
  • Windows PowerShell操作：先执行$env:PYTHONPATH = "你的项目绝对路径\core\python"，再启动VSCode：code .
• 替换自动补全配置：旧的python.autoComplete.extraPaths已不适用于默认的Pylance引擎，需在settings.json中改用python.analysis.extraPaths：

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

让Pylance识别深层命名空间 #

如果上述设置仍不生效，调整Pylance的扫描深度：

• 在settings.json中添加：

  "python.analysis.packageIndexDepths": [
      {
          "name": "common",
          "depth": 2
      }
  ]
  

  这会让Pylance深入扫描common下2级的模块（比如common.somecommonlib）。

额外排查步骤 #

• 确认左下角状态栏选中的是Python 3.10解释器，且该解释器的环境变量包含core/python。
• 按下Ctrl+Shift+P，选择「Python: Reload Window」，让新配置生效。
• 在项目根目录手动创建pyrightconfig.json，加入以下内容强制Pylance读取路径：

  {
      "extraPaths": ["core/python"]
  }
  

无效原因说明 #

• 直接添加core/python/common到PYTHONPATH会让Python把somecommonlib当成顶级模块，而非common.somecommonlib，打乱了命名空间结构。
• python.autoComplete.extraPaths仅对旧版Jedi自动补全引擎有用，现在VSCode默认使用Pylance，必须用python.analysis.extraPaths。

内容的提问来源于stack exchange，提问作者openCivilisation