直接运行 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 和多层结构时：

Li Python Sec Check

Python 安全规范检查工具：基于 CloudBase 规范、腾讯安全指南，LLM 智能分析（默认禁用，优先本地执行）

下载

• 确保目录是合法包：在 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 动态变化。解决它得告诉语言服务器“项目根在哪”：

立即学习“Python免费学习笔记（深入）”；

• 在项目根目录下创建 .env 文件，内容为：PYTHONPATH=${workspaceFolder}
• 确保 VS Code Python 扩展已启用该环境文件（launch.json 中加 "envFile": "${workspaceFolder}/.env"）
• 或者在 .vscode/settings.json 中配置："python.defaultInterpreterPath" 指向正确解释器，并配合 "python.envFile": ".env"
• 别用 sys.path.append() 临时补救——Pylance 看不见那行代码，且破坏可移植性

复杂点在于：调试、终端、Pylance 三者各自维护一套路径逻辑，改一处未必同步生效；最容易被忽略的是 __init__.py 缺失导致包识别失败，或 .env 文件未被 Python 扩展实际加载。