必须验证右下角解释器路径与终端python -c "import sys; print(sys.executable)"输出完全一致，不一致则手动选择或粘贴正确路径，并重启终端；同时配置pythonpath、launch.json的cwd和env，且装包须用python -m pip。
确认解释器路径是否真正生效
VS Code 右下角显示的 Python 路径只是“候选”，不是实际运行时用的。终端里 python -c "import sys; print(sys.executable)" 的输出，才是代码真正加载模块时认的“家”。
- 如果不一致，点右下角 → 选中终端里打印出的路径；列表里没有就选
Enter interpreter path…手动粘贴 - 改完必须关闭所有已打开的终端页签再重开，否则旧环境变量和缓存还在
- Windows 用户注意反斜杠转义问题：
C:\myproject\.venv\Scripts\python.exe和C:/myproject/.venv/Scripts/python.exe在某些场景下不等价
配置 PYTHONPATH 让 Pylance 和运行时同时识别项目结构
PYTHONPATH 是唯一能同时喂饱 Pylance（标红提示）和 Python 解释器（实际运行）的通用开关。别信 code-runner.fileDirectoryAsCwd 或手动 sys.path.append()，那只能骗过一次运行。
- 在项目根目录下创建或编辑
.vscode/settings.json - Windows 用户加这段：
"terminal.integrated.env.windows": { "PYTHONPATH":"${workspaceFolder};${env:PYTHONPATH}" } - macOS/Linux 用户用：
"terminal.integrated.env.osx": { "PYTHONPATH":"${workspaceFolder}:${env:PYTHONPATH}" } - 保存后关掉所有终端再重开；如果仍标红，重启 VS Code（不是重载窗口）
调试时 launch.json 必须配对设置 cwd 和 env.PYTHONPATH
直接点绿色三角运行 main.py 和按 F5 调试，背后机制完全不同。F5 会强制读 launch.json，但默认不设 cwd 和 env.PYTHONPATH，结果就是模块在终端能 import，调试时却报错。
-
program字段必须是相对路径或使用${workspaceFolder}变量，避免硬编码绝对路径 - 务必显式指定
"cwd": "${workspaceFolder}/src"（按你项目实际结构调整） - 配套写入
"env": { "PYTHONPATH": "${workspaceFolder}/src:${env:PYTHONPATH}" } - 若用 pytest，还需同步配置
"python.testing.cwd": "${workspaceFolder}"和"python.analysis.extraPaths": ["${workspaceFolder}"]
装包必须用 python -m pip install，别信裸 pip install
直接敲 pip install requests 很可能调用的是另一个环境里的 pip —— 尤其在 conda、WSL、远程容器中极常见。强制走当前解释器的 pip 才可靠。
- 在已确认解释器路径正确的 VS Code 终端中执行：
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/
路径不一致的问题往往藏在多层嵌套结构里，比如 backend/app/main.py 导入 backend/lib/utils.py，此时 cwd 和 PYTHONPATH 差一个目录层级，错误就会静默发生。
