Sublime Text中import报错需在Build System中显式配置PYTHONPATH绝对路径并匹配虚拟环境解释器路径，否则因构建进程不继承终端环境或执行源码路径操作而失败。
直接改 PYTHONPATH 环境变量最可靠，但必须写在 Build System 配置里，不能靠系统级环境变量或 sys.path.append() 临时加路径 —— Sublime 的构建进程不继承你终端里的 PYTHONPATH，也不运行你的 __init__.py。
为什么 import 报错“No module named xxx”
Sublime Text 默认只把当前文件所在目录加进 Python 模块搜索路径，不会自动识别项目根目录、packages 子目录或虚拟环境 site-packages。哪怕你在终端里能 import 成功，Sublime 构建时仍可能失败。
- 常见现象：
ImportError: No module named utils.database，但该模块明明在./packages/utils/database.py - 根本原因：Python 解释器启动时没被告知去哪找这些包，
sys.path里缺了项目根路径 - 误区：以为改系统环境变量、或在代码开头加
sys.path.insert(0, '..')就能解决 —— 构建是新进程，不执行你源码里的路径操作
在 Build System 中设置 PYTHONPATH
这是唯一稳定生效的方式。新建一个 .sublime-build 文件，显式声明 PYTHONPATH 指向你的项目根目录（即包含 packages/ 或 src/ 的那一层）。
- 打开
Tools → Build System → New Build System - 填入以下内容（注意替换
/path/to/your/project为真实绝对路径）：
{
"shell_cmd": "python3 -u "$file"",
"file_regex": "^[ ]*File "(*?)", line ([0-9]*)",
"selector": "source.python",
"env": {
"PYTHONPATH": "/path/to/your/project"
}
}
-
PYTHONPATH值必须是绝对路径，不能用~或./ - 如果项目结构是
/myproject/packages/utils/...，那PYTHONPATH就设成/myproject，不是/myproject/packages - 多个路径用
:（macOS/Linux）或;（Windows）分隔，例如"/a:/b"
用 virtualenv 时要注意解释器和路径匹配
如果你用的是虚拟环境，光设 PYTHONPATH 不够 —— 还得确保 shell_cmd 调用的是虚拟环境里的 python，否则 site-packages 里的第三方包仍然导入不了。
- 错误写法：
"shell_cmd": "python3 -u "$file""（调用系统 python，无视 venv） - 正确写法：
"shell_cmd": "/path/to/venv/bin/python -u "$file""（macOS/Linux）或"shell_cmd": "C:\path\to\venv\Scripts\python.exe -u "$file""（Windows） -
PYTHONPATH和shell_cmd必须指向同一套环境逻辑：要么都走系统 Python + 手动补路径，要么都走 venv + 自带 site-packages - 验证方式：在代码里加
import sys; print(sys.executable, sys.path)，看输出的解释器路径和sys.path是否符合预期
最容易被忽略的一点：Sublime 的 Build System 是按文件保存后才生效的，改完配置必须手动选中它（Tools → Build System），而且每次切换项目都要换一次 —— 它没有“项目级默认构建系统”的自动绑定机制。如果忘了切换，Ctrl+B 依然会走旧配置，报错也不会提示你配错了地方。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
