1. 多项目依赖与实时更新挑战
在复杂的python项目开发中，一个主应用程序（例如app）常常会依赖于一个或多个内部开发的库（例如lib1, lib2）。这些库通常作为独立的python项目进行管理，并通过如pip install -e git+https://…或poetry等工具以可编辑模式（editable mode）安装到主应用的虚拟环境中。
当开发人员在VS Code的多根工作区中同时处理app和其依赖库时，一个常见的痛点是：对依赖库源代码的修改（例如lib1/__init__.py）并不能立即反映到主应用app的调试运行中。主应用在运行时，默认会加载其虚拟环境中已安装的依赖库版本，而非本地文件系统中最新的源代码。这意味着，每次修改依赖库后，开发者可能需要重新提交、推送代码，然后重新安装依赖，才能在主应用中看到效果，这极大地降低了开发效率。
本教程旨在解决这一问题，允许开发者在不重新安装依赖的情况下，通过VS Code的调试功能，实时查看本地依赖库代码的修改效果，并提供一个跨平台的解决方案。
2. 解决方案核心：利用PYTHONPATH环境变量
Python解释器在导入模块时，会按照特定的顺序查找模块路径。这个查找路径列表可以通过sys.path查看，其中就包含了由PYTHONPATH环境变量指定的路径。通过将本地依赖库的根目录添加到PYTHONPATH中，我们可以强制Python解释器优先加载这些本地路径下的模块，而不是虚拟环境中已安装的旧版本。
然而，PYTHONPATH的路径分隔符在不同操作系统上有所差异：
立即学习“Python免费学习笔记（深入）”；
- Windows 使用分号（;）作为路径分隔符。
- Linux/macOS 使用冒号（:）作为路径分隔符。
为了实现跨平台的调试配置，我们需要在VS Code的launch.json中，针对不同的操作系统提供不同的PYTHONPATH配置。
3. VS Code launch.json的跨平台配置
launch.json是VS Code中用于配置调试器行为的核心文件。它允许我们为特定的调试会话定义各种参数，包括环境变量。通过利用launch.json中的平台特定配置块，我们可以轻松地实现跨平台的PYTHONPATH设置。
假设我们的项目结构如下：
your-parent-folder/ ├── app/ │ ├── .vscode/ │ │ └── launch.json # 调试配置在这里 │ ├── app/__init__.py │ ├── requirements.txt │ └── .venv/ ├── lib1/ │ └── lib1/__init__.py ├── lib2/ │ └── lib2/__init__.py └── product.code-workspace # 多根工作区文件
其中，product.code-workspace文件内容可能如下：
{
"folders": [
{ "path": "app" },
{ "path": "lib1" },
{ "path": "lib2" }
]
}在app项目的.vscode/launch.json文件中，我们可以添加一个调试配置，如下所示：
{
"version": "0.2.0",
"configurations": [
{
"name": "Python: Current File with Live Dependencies",
"type": "python",
"request": "launch",
"program": "${file}",
"console": "integratedTerminal",
"env": {}, // 默认环境变量，可以为空或包含通用变量
// Windows 平台专属配置
"windows": {
"env": {
"PYTHONPATH": "${workspaceFolder}/../lib1;${workspaceFolder}/../lib2"
}
},
// macOS 平台专属配置
"osx": {
"env": {
"PYTHONPATH": "${workspaceFolder}/../lib1:${workspaceFolder}/../lib2"
}
},
// Linux 平台专属配置
"linux": {
"env": {
"PYTHONPATH": "${workspaceFolder}/../lib1:${workspaceFolder}/../lib2"
}
}
}
]
}代码解析：
- "name": 调试配置的名称，会显示在VS Code的调试面板中。
- "type": "python": 指定这是一个Python调试配置。
- "request": "launch": 表示启动一个新的进程进行调试。
- "program": "${file}": 调试当前打开的Python文件。你也可以指定一个固定的入口文件，例如"program": "${workspaceFolder}/app/__init__.py"。
- "console": "integratedTerminal": 在VS Code的集成终端中运行程序。
- "env": {}: 这是一个通用的环境变量对象，适用于所有平台。在这里我们将其留空，因为PYTHONPATH需要平台特定。
- "windows", "osx", "linux": 这些是VS Code launch.json提供的平台特定配置块。在这些块内部定义的环境变量将只在该对应的操作系统上生效。
- "PYTHONPATH": "...": 在每个平台块中，我们设置了PYTHONPATH环境变量。
- "${workspaceFolder}": 这是一个VS Code内置变量，代表当前工作区根目录的路径（在本例中是app目录）。
- "../lib1" 和 "../lib2": 使用相对路径指向lib1和lib2的根目录。这里的路径是相对于app目录的。
- 路径分隔符：根据平台，分别使用了;（Windows）和:（macOS/Linux）。
通过上述配置，当你在VS Code中选择名为 "Python: Current File with Live Dependencies" 的调试配置并启动调试时，Python解释器会首先在lib1和lib2的本地源代码目录中查找模块，从而确保加载的是你最新修改的代码。
4. 注意事项与最佳实践
- 调试与运行的区别：上述launch.json配置仅在通过VS Code调试面板启动调试会话时生效（通常是按F5键或点击调试视图中的“启动调试”按钮）。如果你直接点击编辑器右上角的“运行Python文件”按钮（一个播放图标），它不会使用launch.json中的配置。若要使“运行Python文件”按钮也使用自定义环境变量，你需要配置VS Code的terminal.integrated.env.<platform>设置，但这通常不如launch.json灵活和易于管理。
- 相对路径的优势：在PYTHONPATH中使用"${workspaceFolder}/../lib"这样的相对路径，使得launch.json配置可以在不同的开发环境中（只要项目结构保持一致）通用，无需修改绝对路径。
- 虚拟环境：即使使用了PYTHONPATH，你的主应用仍然应该在其自己的虚拟环境中运行，以管理其它的依赖项。PYTHONPATH只是在模块查找路径中插入了本地依赖库的路径，优先级高于已安装的依赖。
- 版本控制：由于launch.json包含了跨平台的通用配置，你可以安全地将其提交到版本控制系统（如Git）中，以便团队成员共享相同的调试设置。
- 生产环境：此方法主要用于开发和调试。在生产环境中部署时，通常会确保所有依赖库都已正确打包并安装，而不是依赖于本地文件系统的PYTHONPATH设置。
5. 总结
通过在VS Code的launch.json中巧妙地配置平台特定的PYTHONPATH环境变量，开发者可以高效地在多根工作区中调试Python项目，实现主应用对本地依赖库代码的实时更新。这种方法避免了繁琐的重新安装依赖过程，显著提升了开发效率，并提供了一个可跨平台共享的调试配置方案。
