根本原因是Pylance与终端解释器的sys.path不一致：Pylance默认不自动添加项目根目录，需通过.env文件统一配置PYTHONPATH=${workspaceFolder}，并确保解释器、终端、Pylance三者环境对齐，重启VSCode后验证sys.path生效。
为什么 python main.py 能跑，但 VSCode 里 import 就标红？
根本不是代码写错了，而是 VSCode 的 Python 语言服务器（Pylance）和你终端里运行的解释器，压根没在看同一个 sys.path。Pylance 默认只基于当前文件位置推导导入路径，不会自动把项目根目录加进去——哪怕你 main.py 和 utils.py 就在一个文件夹里。
常见表现：
-
from utils import helper运行正常，但编辑器持续报 “Import "utils" could not be resolved” - 终端执行
python -c "import utils"成功，VSCode 调试或运行时却抛ModuleNotFoundError - 切换工作区后，原来能识别的模块突然“消失”
最稳妥的解法：用 .env 文件统一 PYTHONPATH
比改 settings.json 或硬编码 sys.path 更干净，且同时生效于终端、调试器和 Pylance。
操作步骤：
立即学习“Python免费学习笔记（深入）”；
- 在项目根目录（即包含
src/、tests/或app/的那一层）创建.env文件 - 写入：
PYTHONPATH=${workspaceFolder}（Windows 下也用${workspaceFolder}，VSCode 会自动展开） - 确保 VSCode Python 扩展已启用
python.envFile配置（默认已开，无需额外设置） - 重启 VSCode 窗口（仅重载不生效）
验证是否生效：在任意 .py 文件中加 import sys; print(sys.path)，输出里应出现你的项目根路径。
图片提示词生成器？不止如此。 马甲系统 —— 把脑海中的画面，翻译成AI能理解的专业表达。 用得越多，它越懂你：首次需要多问几句确认方向，用久了几乎一说就懂。 用得越多，它越快：缓存机制让后续对话越来越省。 RAG进化：成功案例持续入库，越跑越聪明。 输入「新手指南」查看完整功能介绍
别乱用 from .module import xxx 直接运行就报错
相对导入（带点号）只在模块上下文中合法。如果你双击运行 main.py，或用 python main.py 启动，Python 会把它当“脚本”，而不是包内模块——此时 __name__ == '__main__'，没有父包，from .utils import x 必然触发 SystemError: Parent module '' not loaded。
正确姿势只有两种：
- 用
python -m mypackage.main（前提是mypackage/__init__.py存在，且你在包的父目录下执行） - 放弃相对导入，改用绝对导入 +
PYTHONPATH（如from utils import x），更简单、更少意外
调试时 import 失败？检查 launch.json 的 env 字段
即使配了 .env，如果 launch.json 里手动写了 "env": {}，它会覆盖掉所有环境变量，包括 PYTHONPATH。
安全写法是显式继承：
{
"configurations": [{
"name": "Python: Current File",
"type": "python",
"request": "launch",
"module": "your_module_name", // 或用 "program": "${file}"
"env": {
"PYTHONPATH": "${workspaceFolder}"
}
}]
}
注意："env" 是字典，不是字符串；${workspaceFolder} 不要漏掉 $ 和花括号。
真正容易被忽略的是：VSCode 的 Python 解释器选择、集成终端启动逻辑、Pylance 分析环境这三者必须对齐。改完 .env 后，务必确认状态栏右下角显示的 Python 路径和你 pip install 的环境一致——否则 PYTHONPATH 指向了 A 环境，而解释器在 B 环境里找模块，照样失败。
