Python找不到同级模块的根本原因是运行方式决定sys.path，而非文件位置；python script.py仅将脚本所在目录加入sys.path[0]，而同级目录未被自动包含，正确解法是用python -m启动或sys.path.insert(0,)确保路径优先级。
python script.py 为什么看不见同级目录
因为 Python 只把 script.py 所在目录加进 sys.path[0]，而同级目录（比如 utils/）只是它的兄弟，不是子目录，根本不会被扫描。哪怕 utils/ 里有 __init__.py，import utils 依然报 ModuleNotFoundError。
常见错误现象：
- 在
src/main.py里写from utils import helper，运行python src/main.py失败 - PyCharm 里点绿色三角能跑，终端里
python src/main.py就崩
本质是：工作目录（os.getcwd()）≠ 脚本目录（__file__），而 sys.path 只认工作目录（当用 python script.py 启动时）。
相对导入报 attempted relative import with no known parent package
这个错误不是语法错，是运行上下文错了——Python 认为你这个文件不是模块，而是顶层脚本（__name__ == '__main__'），所以不支持 from . import xxx。
触发条件：
- 直接执行
python utils/helper.py→helper.py是主模块，没父包 -
utils/下缺__init__.py（哪怕空文件也得有） - 没用
-m方式启动，比如python -m utils.helper
正确做法：确保目录结构合规，且统一用 python -m 启动。例如项目根下有 utils/__init__.py 和 main.py，就在根目录执行 python -m main，再在 main.py 里写 from utils import helper。
sys.path.insert(0, ...) 为什么有时还是找不到模块
手动加路径容易失效，不是代码写错了，而是三个细节没控住：
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
- 用
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])确认路径真在列表里
更稳的写法是：sys.path.insert(0, str(Path(__file__).parent.parent))，配合 pathlib.Path 做绝对路径推导，避免字符串拼接翻车。
为什么 PYTHONPATH 在某些场景下也不起作用
PYTHONPATH 只影响 import 语句，对 python script.py 的路径解析逻辑无感。它不解决相对导入、也不改变 sys.path[0] 的行为。
典型失效场景：
- 你在
src/目录下执行python main.py，同时设置了PYTHONPATH=.→ 没用，因为sys.path[0]是src/，而.是上一级 - 用了
python -m启动，但PYTHONPATH指向的是错误层级（比如指向了src/utils而不是项目根）
真正该用 PYTHONPATH 的地方，是长期复用私有工具库（如通用 myutils/），且所有项目都从固定根目录启动。临时调试时，不如直接用 -m 或 pathlib 动态推路径。
最常被忽略的一点：sys.path 是个有序列表，谁在前面谁优先。哪怕你把路径加进去了，只要前面有同名模块（比如你本地写了 requests.py，而 site-packages 里也有 requests），Python 就会静默加载前者——错误可能藏得很深。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
