直接运行 python main.py 报 modulenotfounderror 是因解释器未将 main.py 所在目录加入 sys.path；解决方法有二：一是启用 vs code 的 python.terminal.executeinfiledir 设置使终端在文件目录执行，二是用 python -m src.main（需 src/ 下有 __init__.py）并配好 pythonpath 环境变量。
为什么直接运行 python main.py 会报 ModuleNotFoundError
不是代码写错了，而是 Python 解释器根本没把 main.py 所在目录加进 sys.path。它只认“怎么启动”，不认“文件放在哪”。VS Code 终端默认以项目根目录为工作路径（cwd），但你的 main.py 和 utils.py 可能都在 src/ 下——此时解释器搜索路径里没有 src/，自然找不到同级模块。
让 VS Code 终端真正“站在文件旁边”运行
这是最轻量、见效最快的修复，适合单脚本调试或结构简单的项目：
- 打开 VS Code 设置（
Ctrl+,或Cmd+,），搜索python.terminal.executeInFileDir，勾选它 - 或者在
.vscode/settings.json中加一行："python.terminal.executeInFileDir": true - 右键 → “Run Python File in Terminal” 时，终端会自动
cd到main.py所在目录再执行，sys.path[0]就是该目录，from utils import helper立刻生效 - 注意：此设置不影响
F5调试，调试需另配launch.json中的"cwd": "${fileDirname}"
用 python -m 模式运行（推荐长期项目）
这才是符合 Python 包语义的正解，尤其当你有 __init__.py 和多层结构时：
- 确保目录是合法包：在
src/下放一个空的__init__.py文件 - 不要双击或直接执行
python src/main.py，而是在项目根目录下执行：python -m src.main - 此时
src/被视为顶层包，main.py中可用from .utils import helper（相对导入）或from utils import helper（同级导入） - VS Code 中可通过配置
launch.json的"module"字段实现一键调试："module": "src.main"
Pylance 报红但运行正常？那是静态分析路径没对齐
Import "utils" could not be resolved 这类 Pylance 报错，和运行时错误不同源：它按静态路径推导，不执行代码，也不读 sys.path 动态变化。解决它得告诉语言服务器“项目根在哪”：
- 在项目根目录下创建
.env文件，内容为：PYTHONPATH=${workspaceFolder} - 确保 VS Code Python 扩展已启用该环境文件（
launch.json中加"envFile": "${workspaceFolder}/.env"） - 或者在
.vscode/settings.json中配置："python.defaultInterpreterPath"指向正确解释器，并配合"python.envFile": ".env" - 别用
sys.path.append()临时补救——Pylance 看不见那行代码，且破坏可移植性
__init__.py 缺失导致包识别失败，或 .env 文件未被 Python 扩展实际加载。Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
