根本原因是Python解释器在不同启动方式下对sys.path的初始化逻辑不同：直接执行python main.py会将main.py所在目录加入sys.path[0]，而VS Code默认以工作区根目录为cwd，导致子目录模块无法被识别。
为什么 import 报错，但 python main.py 却能跑通
根本原因不是代码写错了，而是 Python 解释器在不同启动方式下对 sys.path 的初始化逻辑完全不同。直接执行 python main.py 时，解释器会自动把 main.py 所在目录塞进 sys.path[0]；而 VS Code 默认以工作区根目录为终端 cwd，哪怕你的 main.py 在 src/ 下，sys.path 里也不会包含 src/。
常见现象包括：
-
ModuleNotFoundError: No module named 'utils'（但utils/就在同级） - Pylance 持续报红
Import "xxx" could not be resolved，可运行却无误 -
from .xxx import yyy触发SystemError: Parent module '' not loaded
让终端“站在文件旁边”执行：启用 python.terminal.executeInFileDir
这是最快见效的轻量方案，适合单脚本调试或结构扁平的项目。
它强制 VS Code 在右键「Run Python File in Terminal」时，先 cd 到当前文件所在目录再执行，从而让 sys.path[0] 等于该目录。
立即学习“Python免费学习笔记（深入）”；
操作方式：
- 快捷键
Ctrl+,打开设置，搜索python.terminal.executeInFileDir，勾选启用 - 或手动编辑
.vscode/settings.json，添加："python.terminal.executeInFileDir": true
注意：此设置不影响 F5 调试——调试仍走 launch.json，需单独配 "cwd": "${fileDirname}"。
用 python -m 模式运行：符合 Python 包语义的正解
当你有分层结构（如 src/main.py + src/utils.py）且希望长期维护时，这才是推荐路径。
SkillSub Pro - Python 题解与代码注释双功能技能功能概述SkillSub Pro - Python 题解与代码注释双功能技能是一项面向实际任务的技能，主要用于SkillSub Pro 是一个 Python 题解生成与代码注释的 双功能合体技能 ，专为学生、算法学习者和开发者设计；✅ 一个技能，两种用途 ：；核心要点📝 题解模式 ：输入题目/题号，自动生成完整 Python 题解（含详细注释、解题思路、复杂度分析）；💬 注释模式 ：输入 Python 代码，自动添加详细中。它将相关步骤、
它要求目录是合法包（含 __init__.py），并让 Python 将该目录视为顶层模块上下文，支持相对导入和干净的绝对导入。
关键点：
- 必须在项目根目录下执行，例如：
python -m src.main（不是python src/main.py） - VS Code 中可在
launch.json里配置："module": "src.main"，F5 即按包语义调试 - 终端中若想复现，需确保
cwd是项目根目录，而非src/
绕过这个模式硬写 sys.path.append('..') 或 os.getcwd()，等于把路径逻辑耦合进业务代码，CI/CD 和他人协作时极易出错。
统一环境变量：用 .env 或 settings.json 注入 PYTHONPATH
当项目依赖多个并列子包（如 shared_libs/、services/），且不希望每个地方都改 sys.path 时，用环境变量注入最稳妥。
两种主流方式：
- 在项目根目录建
.env文件，写入：PYTHONPATH=${workspaceFolder}（VS Code Python 插件会自动读取） - 或在
.vscode/settings.json中加："terminal.integrated.env.windows": { "PYTHONPATH": "${workspaceFolder}" }
区别在于生效范围：.env 对调试、终端、Pylance 都有效；而 settings.json 中的 env 配置仅影响集成终端，不作用于调试器或静态分析工具。
容易忽略的一点：如果同时存在多个 PYTHONPATH 设置（比如系统级 + 用户级 + 工作区级），它们会被拼接，顺序很重要——靠前的路径优先匹配，冲突时可能意外覆盖预期行为。
