VSCode中Python模块导入报ModuleNotFoundError，90%是PYTHONPATH未正确配置所致；调试（F5）与终端（Ctrl+`）使用不同sys.path初始化逻辑，需通过launch.json配env、settings.json配终端环境变量或项目根目录的.env文件统一解决。
VSCode里Python模块导入报ModuleNotFoundError，90%不是代码问题，而是PYTHONPATH没设对——解释器根本没去你放模块的目录找。
为什么调试能跑、终端却报错？
因为VSCode的调试器（F5）和集成终端（Ctrl+`）用的是两套sys.path初始化逻辑：
- 终端执行
python xxx.py时，Python自动把脚本所在目录塞进sys.path[0] - 调试器默认不加项目根目录，只认
launch.json里显式配的cwd或env - 验证方法：在出错文件开头加
import sys; print(sys.path)，对比终端输出和调试器输出的前几项
launch.json配env：只影响F5调试
这是最干净的调试专用方案，不影响终端或其他工具。修改.vscode/launch.json，在对应配置里加env字段：
{
"version": "0.2.0",
"configurations": [
{
"name": "Python: 当前文件",
"type": "python",
"request": "launch",
"program": "${file}",
"console": "integratedTerminal",
"env": {
"PYTHONPATH": "${workspaceFolder};${env:PYTHONPATH}"
}
}
]
}
-
${workspaceFolder}是项目根目录，Windows下路径用分号;拼接，Linux/macOS用冒号: -
${env:PYTHONPATH}保留原有值，避免覆盖系统级路径 - 改完必须重启调试会话，否则不生效
settings.json配terminal.integrated.env.*：只影响终端
如果你主要靠终端运行脚本（比如python -m pytest或python main.py），就配这个：
macOS UI 自动化技能包 —— 用 Python 控制你的 Mac
下载
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
立即学习“Python免费学习笔记（深入）”；
- 在项目根目录的
.vscode/settings.json里加："terminal.integrated.env.windows": {"PYTHONPATH": "${workspaceFolder}"} - Linux/macOS换键名：
terminal.integrated.env.linux或terminal.integrated.env.osx - 别写死绝对路径，
${workspaceFolder}变量安全且跨平台 - 改完要重启VSCode窗口，否则终端环境变量不会刷新
.env文件：终端+调试+测试全生效
这是最稳的方案，VSCode Python插件会自动加载它，对所有运行方式都起作用：
- 在项目根目录新建
.env文件，内容只有一行：PYTHONPATH=${workspaceFolder} - Windows多个路径用
;分隔，如：PYTHONPATH=${workspaceFolder};${workspaceFolder}/src - Linux/macOS用
:分隔 - 不需要重启VSCode，但确保已安装最新版Python插件（v2026.6+）
注意：python.analysis.extraPaths只影响Pylance提示，完全不改变sys.path——它解决“标红但能跑”，不解决ModuleNotFoundError。
