ModuleNotFoundError主因是解释器、PYTHONPATH与sys.path三者不一致；需验证右下角解释器路径与终端python -c "import sys; print(sys.executable)"输出完全一致，配置.vscode/settings.json和launch.json中PYTHONPATH与cwd，并用python -m pip安装包。
不是没装包，是 VS Code 根本没在找你放包的地方。 所有 ModuleNotFoundError 报错，90% 以上都卡在路径识别这一步：解释器、PYTHONPATH、sys.path 三者不一致，导致运行时和编辑器标红各走各的路。
确认解释器路径是否真正生效
VS Code 右下角显示的 Python 路径只是“候选”，终端里跑的才是真实环境。不验证就动手装包，等于往隔壁房间堆货。
- 打开内置终端（
Ctrl + `），立刻执行：python -c "import sys; print(sys.executable)" - 输出路径必须和右下角显示的**完全一致**；哪怕多一个空格、少一个反斜杠，都不算生效
- 如果不一致，点右下角 → 选中那个终端里打印出的路径；如果列表里没有，选 Enter interpreter path… 手动粘贴
- 改完后必须关闭所有已打开的终端页签再重开，否则旧环境变量和缓存还在
让 Pylance 和运行时都认得你的项目结构
PYTHONPATH 是唯一能同时喂饱 Pylance（标红提示）和 Python 解释器（实际运行）的通用开关。别信 code-runner.fileDirectoryAsCwd 或手动改 sys.path，那只能骗过一次运行。
- 在项目根目录下创建或编辑
.vscode/settings.json - Windows 用户加这段：
"terminal.integrated.env.windows": { "PYTHONPATH": "${workspaceFolder};${env:PYTHONPATH}" } - macOS/Linux 用户用：
"terminal.integrated.env.osx": { "PYTHONPATH": "${workspaceFolder}:${env:PYTHONPATH}" } - 保存后关掉所有终端再重开；如果仍标红，重启 VS Code（不是重载窗口）
调试时 cwd 和 PYTHONPATH 必须配对出现
直接点绿色三角运行 main.py，和 F5 调试，背后机制完全不同。F5 会强制读 launch.json，但默认不设 cwd 和 env.PYTHONPATH，结果就是模块在终端能 import，调试时却报错。
立即学习“Python免费学习笔记（深入）”；
- 确保
.vscode/launch.json中有这两项："cwd": "${workspaceFolder}", "env": { "PYTHONPATH": "${workspaceFolder}" } - 如果项目结构是
src/main.py且要从src.utils导入，cwd得设成${workspaceFolder}/src，PYTHONPATH也得同步改成${workspaceFolder}/src - 别用
console: "externalTerminal"—— 外部终端不会继承launch.json的env
装包必须绑定当前解释器，别信裸 pip
pip install requests 看似简单，实则危险。它调用的是系统 PATH 里的 pip，极大概率不是你当前解释器附带的那个。
- 只用这一种方式装包：
python -m pip install requests - 批量装：
python -m pip install -r requirements.txt - 升级 pip 自身：
python -m pip install --upgrade pip - 国内用户加清华源：
python -m pip install numpy -i https://pypi.tuna.tsinghua.edu.cn/simple/ - 装完后，在终端里运行
python -c "import requests; print(requests.__file__)"，确认路径落在你当前解释器的site-packages下
最常被跳过的动作是：改完 settings.json 或 launch.json 后没关终端、没重启 VS Code、没验证 sys.executable 是否真同步——这些步骤缺一不可，漏一个，ModuleNotFoundError 就照常报。
