必须验证右下角显示路径与终端sys.executable完全一致，否则解释器未真正生效；不一致需手动重选路径并重启终端，Mac用户还需注意GUI启动时pyenv/conda初始化可能缺失。
确认解释器路径是否真正生效
VSCode右下角显示的Python路径只是“候选”，终端里跑的才是真实环境。不验证就装包，等于往隔壁房间堆货。
打开内置终端（Ctrl + `），立刻执行：python -c "import sys; print(sys.executable)"。输出路径必须和右下角显示的**完全一致**；哪怕多一个空格、少一个反斜杠，都不算生效。
- 如果不一致，点右下角 → 选中终端里打印出的路径；如果列表里没有，选
Enter interpreter path…手动粘贴 - 改完后必须关闭所有已打开的终端页签再重开，否则旧环境变量和缓存还在
- Mac用户特别注意：双击图标启动 VS Code 时，
~/.zshrc中的pyenv或conda初始化逻辑可能未加载，导致终端 PATH 和 GUI 进程不一致
让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，调试时却报错。
在.vscode/launch.json中确保配置匹配：
-
"program"指向脚本路径，但"cwd"必须设为该脚本所在目录的父级（比如main.py在backend/下，"cwd"应为"${workspaceFolder}/backend"） -
"env": { "PYTHONPATH": "${workspaceFolder}/backend" }—— 这个值要和cwd一致，否则from open_webui.utils这种跨目录导入仍失败 - 不要只改
cwd不设PYTHONPATH，二者缺一不可
装包必须用 python -m 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/
最常被忽略的一点：python -m pip show xxx 输出的 Location 必须落在你当前解释器的 site-packages 目录下，而不是系统路径或别的虚拟环境里。否则一切配置都白搭。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
