解决 VSCode 中 Python 本地模块导入问题的方法

解决 VSCode 中 Python 本地模块导入问题的方法

要在 VSCode 中使用规范的绝对导入（如 from my_project.package1 import module1）并避免 ModuleNotFoundError，需要正确配置 PYTHONPATH 环境变量。关键在于区分不同运行方式和操作系统。

方法一：配置 launch.json（适用于 F5 调试运行）

1. 在项目根目录下的 .vscode 文件夹中打开或创建 launch.json。

2. 在配置中添加 "env" 字段来设置 PYTHONPATH：

   {
       "version": "0.2.0",
       "configurations": [
           {
               "name": "Python: Current File",
               "type": "python",
               "request": "launch",
               "program": "${file}",
               "console": "integratedTerminal",
               "justMyCode": false,
               "env": {
                   // Windows 使用分号 ";"
                   "PYTHONPATH": "${workspaceFolder};${env:PYTHONPATH}"
                   // Linux/macOS 使用冒号 ":"
                   // "PYTHONPATH": "${workspaceFolder}:${env:PYTHONPATH}"
               }
           }
       ]
   }
   

   注意：此方法仅对通过 VSCode 的 F5（调试） 运行方式有效。

方法二：配置 settings.json（适用于 VSCode 终端运行）

1. 打开 VSCode 设置 (Ctrl/Cmd + ,)。

2. 搜索 terminal.integrated.env。

3. 点击对应操作系统的 “Edit in settings.json” 链接（通常建议修改用户 settings.json 以确保继承）。

4. 在 settings.json 中添加终端环境变量配置：

   {
       // ... 其他设置 ...
       // Windows 环境下为终端设置环境变量
       "terminal.integrated.env.windows": {
           "PYTHONPATH": "${workspaceFolder};${env:PYTHONPATH}"
       },
       // Linux/macOS 环境下为终端设置环境变量
       // "terminal.integrated.env.linux": {
       //     "PYTHONPATH": "${workspaceFolder}:${env:PYTHONPATH}"
       // },
       // "terminal.integrated.env.osx": {
       //     "PYTHONPATH": "${workspaceFolder}:${env:PYTHONPATH}"
       // }
   }
   

   注意：

   • 修改 settings.json 后，必须关闭并重新打开 VSCode 或至少重新启动集成终端，配置才会生效。
   • 此方法使得在 VSCode 集成终端中直接运行 python script.py 也能正确识别模块路径。

关键点总结

• 操作系统差异：
  • Windows: PYTHONPATH 内部用 ; 分隔路径。
  • Linux/macOS: PYTHONPATH 内部用 : 分隔路径。
  • 配置错误会导致路径解析失败。
• 配置范围：
  • launch.json -> 仅 F5 调试。
  • settings.json (terminal.integrated.env) -> VSCode 终端。
• 推荐做法：同时配置 launch.json 和 settings.json（根据操作系统选择正确的分隔符），以覆盖所有运行场景。优先修改用户 settings.json 通常更稳定。