直接运行脚本报ModuleNotFoundError，是因为Python仅在sys.path中查找模块，而当前脚本所在目录不一定在sys.path中；工作目录（os.getcwd()）决定默认搜索路径，而非脚本位置（__file__），导致同级模块无法被定位。
为什么直接运行脚本会报 ModuleNotFoundError？
因为 Python 默认只在 sys.path 里找模块，而当前脚本所在目录（同级模块实际位置）**不一定在 sys.path 中**。关键变量是工作目录（os.getcwd()），不是脚本位置（__file__）。比如你在项目根目录下执行 python src/main.py，Python 就会把项目根目录加进 sys.path[0]；但如果你 cd 进 src/ 再运行 python main.py，它才把 src/ 加进去——可这时 module.py 在同级，反而找不到。
import sys; sys.path.append(...) 容易踩的坑
临时加路径看似简单，但极易出错：
- 用
os.path.dirname(__file__)是对的，但别漏掉os.path.abspath——否则相对路径在某些调用方式下会失效 -
sys.path.append()是追加到末尾，优先级最低；如果同名模块已存在于标准库或 site-packages，你的本地模块根本不会被选中 - 加完路径后没验证：建议加一行
print([p for p in sys.path if 'your_dir' in p])确认路径真加进去了 - 多人协作时，这种硬编码路径会让别人一运行就报错，属于“能跑但不该这么写”
真正可靠的导入方式：用 python -m 启动
这是官方推荐、也是最干净的方案，前提是项目结构合规：
macOS UI 自动化技能包 —— 用 Python 控制你的 Mac
下载
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
- 确保目标模块所在目录有
__init__.py（哪怕空文件） - 模块名必须是合法的 Python 标识符（不能含短横线、空格等）
- 从项目根目录运行，例如：
python -m mypackage.main，Python 会自动把当前目录加入sys.path[0] - 此时
from . import module或from mypackage import module都能正常工作
PYTHONPATH 适合什么场景？
它适合长期开发中固定引用某几个私有工具库，比如你有一套通用的 utils/ 目录，想在多个项目里复用：
立即学习“Python免费学习笔记（深入）”；
- 临时设置：
export PYTHONPATH="/path/to/utils:$PYTHONPATH"（Linux/macOS）或set PYTHONPATH=C:\path\to\utils;%PYTHONPATH%（Windows） - 永久生效：写入
~/.bashrc或~/.zshrc，然后source；Windows 用户可设系统环境变量 - 注意：它不解决包内相对导入问题，也不影响
python script.py的行为，只对import语句起作用 - 调试时可用
python -c "import sys; print(sys.path)"验证是否生效
最常被忽略的是：__file__ 和工作目录不是一回事，而 sys.path 的顺序决定了谁赢——哪怕你加了路径，如果前面已有同名模块，它就永远加载不到你的版本。
