vscode中python模块导入失败90%因sys.path未包含项目根目录，调试进程与终端独立，需通过launch.json配置cwd和pythonpath确保路径一致。
VSCode里Python模块导入失败，90%是因为sys.path没对上——不是代码写错了，是解释器根本没看到你的目录。
为什么终端能跑，VSCode调试就报ModuleNotFoundError
Python解释器启动时会初始化sys.path，顺序查：当前脚本所在目录 → PYTHONPATH环境变量路径 → 标准库 → site-packages。VSCode调试时默认只把被调试文件所在目录加进去，不会自动包含项目根目录或src这类逻辑根目录。
常见错误现象：
- 在终端执行
python tests/test_main.py成功，但VSCode点击“运行调试”直接报错 -
import src.utils.helper在PyCharm里没问题，VSCode里标红 -
print(sys.path)发现输出里压根没有your-project-root
关键点：VSCode的调试进程和终端进程是两个独立Python实例，sys.path互不影响。
launch.json里配env和cwd最稳
这是VSCode官方推荐、且对调试/运行都生效的方式。直接控制调试进程的起始工作目录和环境变量。
操作步骤：
- 在项目根目录下建
.vscode/launch.json（如果还没建） - 确保
configurations里有类似这样的配置：
{
"version": "0.2.0",
"configurations": [
{
"name": "Python: Current File",
"type": "python",
"request": "launch",
"module": "pytest",
"cwd": "${workspaceFolder}",
"env": {
"PYTHONPATH": "${workspaceFolder}"
}
}
]
}
注意：
-
cwd设为${workspaceFolder}，保证open("config.yaml")这类相对路径也按项目根解析 -
PYTHONPATH值必须是绝对路径，${workspaceFolder}会被VSCode自动展开 - 如果项目结构是
src/为实际包根（比如src/mylib/__init__.py），就把PYTHONPATH改成"${workspaceFolder}/src"
别在代码里硬写sys.path.append()
临时加路径看似快，但隐患明显：
Python 3.14.2是Python编程语言在2025年12月5日发布的稳定版本，属于3.14系列的第二个维护更新。该版本包含了18项修复，重点解决了多进程、数据类及正则表达式等模块的回归问题，并修复了CVE-2025-12084等安全漏洞。此版本标志着自由线程模式（移除GIL）正式获得官方支持，是Python发展的重要里程碑。
- 路径写死（如
../..）容易因执行位置不同而失效 - 不同IDE或CI环境行为不一致，本地能跑，CI挂掉
- 调试器可能在加载模块前就已初始化
sys.path，此时append晚了
真要动态处理（比如无法改launch.json的CI场景），用这个更健壮的写法：
import sys import os <h1>获取当前文件所在目录的父级目录（即项目根）</h1><p>project_root = os.path.dirname(os.path.dirname(os.path.abspath(<strong>file</strong>))) if project_root not in sys.path: sys.path.insert(0, project_root)</p>
但记住：这只是兜底方案，优先走launch.json或settings.json配置。
settings.json配terminal.integrated.env.*只管终端
这个配置只影响VSCode集成终端（也就是你Ctrl+`打开的那个黑窗口），对调试器完全无效。
适用场景有限：
- 你想在集成终端里直接
python -m pytest tests/能跑通 - 项目里大量依赖
pip install -e .，但又不想每次手动激活venv
Windows下加到.vscode/settings.json：
"terminal.integrated.env.windows": {
"PYTHONPATH": "${workspaceFolder}"
}
macOS/Linux对应用env.osx或env.linux。别漏掉平台后缀，否则不生效。
真正容易被忽略的是：launch.json里的env和settings.json里的terminal.integrated.env.*是两套机制，各自生效范围完全不同。混用时得清楚自己改的是谁的路径。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
