vscode中python脚本报modulenotfounderror但终端可运行，根本原因是未将项目根目录加入模块搜索路径；解决方法是在项目根目录创建.env文件写入pythonpath=.并重启语言服务器。
VSCode 中 Python 脚本运行时报 ModuleNotFoundError，但终端里 python main.py 能跑通——这基本不是模块没装，而是 VSCode 没把当前项目目录当“根”来搜模块。
为什么 VSCode 不认 from src.utils import helper
Python 解释器本身只在 sys.path 列表里找模块；VSCode 的 Python 语言服务器（Pylance）、调试器、补全引擎默认不自动把项目根加进去。尤其当你用相对路径跨文件夹导入（比如 src/ 和 tests/ 平级），它根本不知道 src 是个包。
常见现象：
- 代码能运行，但编辑器标红、无跳转、无补全
-
import src.utils提示 “Unable to import 'src.utils'”（pylint 或 Pylance 报错） - F5 调试失败，而终端里
python -m src.main成功
设置 PYTHONPATH 让所有工具认得项目根
最稳定、一劳永逸的方法：告诉 VSCode（及其所有子系统）“这个文件夹就是我的模块起点”。不是改解释器路径，也不是硬塞 sys.path.append()。
操作步骤：
- 在项目根目录下创建一个
.env文件（和pyproject.toml或requirements.txt同级） - 写入一行：
PYTHONPATH=.（注意是点号，不是空格或引号） - 关闭并重启 VSCode（或至少重启 Python 语言服务器：
Ctrl+Shift+P→Python: Restart Language Server）
这样之后，from src.utils import helper、import mypackage 全部被 Pylance、调试器、linting 识别。不需要改任何 __init__.py，也不依赖 pip install -e .。
Python 3.14.2是Python编程语言在2025年12月5日发布的稳定版本，属于3.14系列的第二个维护更新。该版本包含了18项修复，重点解决了多进程、数据类及正则表达式等模块的回归问题，并修复了CVE-2025-12084等安全漏洞。此版本标志着自由线程模式（移除GIL）正式获得官方支持，是Python发展的重要里程碑。
避免踩坑：别在 settings.json 里硬写 python.defaultInterpreterPath
很多教程让你在 .vscode/settings.json 里填死解释器路径，这是隐患源头：
- 路径写错（比如指向系统 Python 而非虚拟环境）→
pip install装到别处 - 团队协作时路径不一致 → 同一份代码，别人打开就报错
- VSCode 缓存旧路径 → 即使你换了环境，它还在用上个月的
python3.9
正确做法：
- 删掉
.vscode/settings.json里的python.defaultInterpreterPath字段 - 用
Ctrl+Shift+P→Python: Select Interpreter选中你激活的虚拟环境下的python可执行文件（路径结尾是/venv/bin/python或\venv\Scripts\python.exe） - 确认底部状态栏显示的解释器路径，和你在终端里运行
which python的输出完全一致
调试时仍报错？检查终端和调试器是否用了同一个环境
这是最隐蔽的问题：你在集成终端里 pip install requests 成功了，F5 调试却报 ModuleNotFoundError。原因往往是：
- 终端已激活虚拟环境，但调试器启动时没读
.env或没继承环境变量 -
launch.json里没指定python路径，回退到默认解释器
验证方法：
- 在调试器里加一行：
import sys; print(sys.executable)，看输出路径是否和你选的解释器一致 - 确保
.vscode/launch.json中有："python": "${command:python.interpreterPath}" - 或者直接删掉
launch.json，让 VSCode 用当前选中的解释器自动配置
复杂点在于：.env 对调试器生效，但对终端不自动生效（除非你手动 source .env）。所以统一用 PYTHONPATH=. + 正确解释器选择，比到处 patch sys.path 更可靠。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
