Python找不到同级模块的根本原因是运行方式决定sys.path，而非文件位置；python script.py仅将脚本所在目录加入sys.path[0]，而同级目录未被自动包含，正确解法是用python -m启动或sys.path.insert(0, ...)确保路径优先级。
Python 找不到同级目录下的模块，不是因为你漏写了 __init__.py，也不是因为文件名拼错了——最常见原因是：你运行脚本的方式，让 Python 根本没把那个“同级目录”放进 sys.path。
python script.py 和 python -m package.script 的行为完全不同
这是所有问题的起点。Python 解释器决定模块搜索路径（sys.path）的第一依据是「启动方式」，而不是文件位置。
-
python main.py：把main.py所在目录加到sys.path[0]，但它的同级目录（比如utils/）只是子目录，不会被当作包自动扫描 -
python -m mypackage.main：要求mypackage/是一个包（含__init__.py），此时 Python 会把mypackage/的父目录加入sys.path，从而支持from . import utils或import mypackage.utils - IDE（如 PyCharm）默认把项目根设为 Sources Root，相当于偷偷加了
PYTHONPATH——终端里一跑就失败，纯属环境错觉
sys.path.append() 为什么经常失效
手动加路径看似直白，但有三个硬伤：
- 用
os.path.dirname(__file__)而不套os.path.abspath()：遇到符号链接或相对路径调用时，返回的可能是空字符串或错误路径 - 用
sys.path.append()：追加到末尾，优先级最低；如果标准库或site-packages里有同名模块（比如你叫json.py），你的版本永远加载不上 - 没验证是否真加进去了：加完不 print 一遍
[p for p in sys.path if 'utils' in p]，等于盲操作
相对导入（from . import xxx）报 attempted relative import 错误
这个错误不是语法错，是运行上下文错。相对导入只在模块内有效，不能用于顶层脚本。
macOS UI 自动化技能包 —— 用 Python 控制你的 Mac
下载
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
立即学习“Python免费学习笔记（深入）”；
-
python utils/helper.py→ helper.py 是主模块（__name__ == '__main__'），没有父包，from . import xxx直接崩 -
python -m utils.helper→ helper.py 成为模块，__name__变成utils.helper，此时from . import xxx才合法 - 想用相对导入，必须确保：① 目录有
__init__.py；② 用-m运行；③ 不在该目录下直接执行.py文件
真正能跨环境稳定的方案只有两个
别纠结 __init__.py 存不存在（Python 3.3+ 已非必需），重点是路径控制权交到谁手上。
- 开发阶段：统一用
python -m project.main，前提是项目根目录下有__init__.py，且main.py移到project/内。这样sys.path固定，导入逻辑可预测 - 部署或工具脚本：用
pathlib.Path(__file__).parent获取绝对路径，再sys.path.insert(0, str(...))——插在开头，压过系统路径，且必须用insert(0)而非append()
最常被忽略的细节是：__file__ 指的是当前文件路径，而 os.getcwd() 是终端当前所在目录，两者八竿子打不着；但 sys.path 的顺序决定了哪个模块胜出——哪怕你加了路径，前面已有同名模块，你的代码就静默失效。
