根本原因是vscode的python执行路径有四套独立环境：调试（f5）、终端（ctrl+`）、右键运行、交互式窗口，每种方式加载pythonpath的机制和优先级不同且互不继承。
为什么 PYTHONPATH 在 VSCode 里“有时生效、有时失效”
根本原因不是配置错了，而是 VSCode 的 Python 执行路径有四套独立环境：调试（F5）、终端（Ctrl+`）、右键“运行 Python 文件”、交互式窗口。每种方式加载 PYTHONPATH 的机制和优先级都不同，且互不继承。比如你在 launch.json 里写了 PYTHONPATH，它只影响 F5 调试；但你在终端敲 python main.py，这个变量压根没被读到。
常见错误现象：
- 调试时
from utils.helper import x正常，终端运行就报ModuleNotFoundError - 改了
settings.json却发现 pylint 还在标红，但运行又没问题 -
.env文件里的PYTHONPATH=.在交互式窗口生效，终端里却是None
launch.json 的 env 配置：仅限调试生效
这是最常用也最容易误解的一层。它只作用于按下 F5 或点击“运行调试”时的进程，不影响终端或右键运行。
实操建议：
- 必须写在
configurations数组的具体配置项里，不能放在顶层 - Windows 下用分号
;拼接路径，Linux/macOS 用冒号:，混用会导致整个变量失效 - 推荐写成
"PYTHONPATH": "${workspaceFolder};${env:PYTHONPATH}"，保留原有值避免覆盖系统级路径 - 如果项目含多级子包（如
src/core/），要把src加进去："${workspaceFolder}/src;${workspaceFolder}"
terminal.integrated.env.*：控制集成终端行为
这是让 python script.py 在 Ctrl+` 里能跑通的关键。它不修改系统 PATH，只影响 VSCode 启动的终端进程。
实操建议：
- 必须按操作系统分别配置：
terminal.integrated.env.windows、terminal.integrated.env.linux、terminal.integrated.env.osx - 值必须是对象，不能是字符串，例如：
{"PYTHONPATH": "${workspaceFolder};${env:PYTHONPATH}"} - 这个配置对“右键 → 在终端中运行 Python 文件”也生效，但对“在 Python 终端中运行选中代码”无效
- 注意：重启终端才能生效，已打开的终端不会自动刷新环境变量
python.envFile + python-dotenv：跨所有场景的兜底方案
python.envFile 设置本身只被调试器和 linter 读取，但配合 python-dotenv 库，就能在任何执行方式下强制加载 .env 里的 PYTHONPATH。
实操建议：
- 在
.vscode/settings.json中设"python.envFile": "${workspaceFolder}/.env"（仅辅助调试识别） - 在项目根目录建
.env，内容写成PYTHONPATH=.或PYTHONPATH=./src:./lib - 在脚本开头加两行：
from dotenv import load_dotenv和load_dotenv() - 不要依赖 VSCode 自动加载
.env—— 它在终端直跑时大概率不工作，显式调用才可靠
真正容易被忽略的是路径拼接顺序：sys.path 是从左到右扫描的，如果 PYTHONPATH 把第三方包路径放在前面，可能意外覆盖标准库模块。务必把项目根目录放在最前，再拼接其他路径。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
