vscode默认不将项目根目录加入python模块搜索路径，导致modulenotfounderror；需通过launch.json设pythonpath（调试）、settings.json配terminal.integrated.env.*（终端）或python.analysis.extrapaths（pylance提示）分场景解决。
VSCode默认不把项目根目录加进Python模块搜索路径，所以只要不是当前文件同级的模块，基本都会报ModuleNotFoundError。这不是你代码写错了，是环境没配对。
为什么sys.path里没有你的项目目录？
Python解释器只按固定顺序查路径：当前脚本所在目录 → PYTHONPATH环境变量 → Python安装目录和site-packages。VSCode不会像PyCharm那样自动把${workspaceFolder}塞进去。
验证方法：在出错的文件里加两行：
import sys print(sys.path)
运行后看输出列表——如果项目根目录（比如e:\my_project）不在其中，就确认是路径问题。
- 调试（F5）和终端（Ctrl+`）用的是两套环境变量，可能一个能跑一个报错
-
from ..utils import helper这类相对导入，必须确保父包在sys.path中，否则直接失败 - Windows下路径分隔符用
;，不是:；Linux/macOS才用:
用launch.json配PYTHONPATH（仅F5调试生效）
这是最干净的调试专用方案，不影响终端或其他工具。修改.vscode/launch.json，在对应配置里加env字段：
{
"name": "Python: Current File",
"type": "python",
"request": "launch",
"program": "${file}",
"env": {
"PYTHONPATH": "${workspaceFolder};${env:PYTHONPATH}"
}
}
注意点：
-
${env:PYTHONPATH}保留原有值，避免覆盖系统或虚拟环境里的路径 - 如果项目结构是
src/下放代码，把${workspaceFolder}换成${workspaceFolder}/src - 改完必须重启调试会话，热重载不生效
用settings.json配terminal.integrated.env.*（终端和Pylint都生效）
想让集成终端（Ctrl+`）里跑python main.py也正常，或者让Pylint不再标红Unable to import，就得走这个路子。
编辑.vscode/settings.json，加上：
{
"terminal.integrated.env.windows": {
"PYTHONPATH": "${workspaceFolder}"
}
}
关键细节：
- Windows用
terminal.integrated.env.windows，macOS/Linux用terminal.integrated.env.linux或terminal.integrated.env.osx - 这个设置只影响VSCode启动的新终端，已打开的终端要关掉重开
- Pylint、Pylance的静态分析依赖这个环境变量，但
python.analysis.extraPaths只是给语言服务用，不改变真实sys.path
python.analysis.extraPaths是给Pylance看的，不是给Python解释器用的
很多人误以为设了python.analysis.extraPaths就能解决运行时导入，其实它只影响VSCode的代码补全和错误提示，跟实际执行完全无关。
正确用法（仅用于消除Pylint/Pylance标红）：
{
"python.analysis.extraPaths": ["src", "tests"]
}
注意：
- 路径是相对于
${workspaceFolder}的，不是绝对路径 - 这里填
"src"，不代表import utils.helper就能通；运行时仍需PYTHONPATH或sys.path.append() - 如果填了绝对路径（如
"c:/my_project/src"），换机器就失效
真正容易被忽略的是：调试、终端、Pylint三者路径来源互不干扰。你得根据使用场景选对配置位置，而不是堆砌所有方案——重复设置反而可能引发冲突。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
