__main__.py是Python包作为命令行程序运行的必要条件，解释器执行python -m package_name时硬编码查找该文件（与__init__.py同级、名称严格匹配），缺失则报错；它定义包级入口，与单文件的if __name__ == "__main__":属不同层级机制。
__main__.py 不是可选的装饰，而是包能被当作命令行程序直接运行的**必要条件**。没有它，python -m mypackage 会报 ImportError: No module named '__main__'。
执行 python -m package_name 时发生了什么
Python 解释器收到 -m 参数后，会把 package_name 当作一个模块路径去解析，然后尝试加载它的 __main__.py —— 这不是约定，是硬编码行为。它不会去找 __init__.py，也不会退而求其次执行某个 main.py。
- 必须存在且位于包根目录下（与
__init__.py同级） - 文件名必须严格为
__main__.py，大小写、下划线数量都不能错 - 如果包嵌套多层（如
foo.bar.baz），只有最末一级（baz/__main__.py）会被执行
__main__.py 和 if __name__ == '__main__' 的关系
二者解决的是不同层级的问题：if __name__ == '__main__' 是单个 Python 文件的“自检开关”，而 __main__.py 是整个包的“启动契约”。你完全可以在 __main__.py 里不写这个判断——因为该文件**只会在顶层环境执行**，__name__ 永远是 '__main__'，根本不会被 import 触发。
- 在
__main__.py中写if __name__ == '__main__': ...是冗余的，纯属习惯性复制粘贴 - 但你可以（也应该）在里面调用一个真正的
main()函数，便于单元测试和逻辑复用 - 别把初始化逻辑全塞进
__main__.py；包级配置、日志设置等应放在__init__.py中
常见错误：为什么 python mypackage/ 不起作用
很多人误以为只要目录结构对，就能像 shell 脚本一样直接运行包目录。但 Python **不支持**这种语法。直接执行目录会报 Permission denied 或 Can't find '__main__.py' in directory 类似错误，因为解释器根本不按目录路径解析。
-
python mypackage/❌ —— 这不是合法命令，解释器会尝试把它当文件打开 -
python -m mypackage✅ —— 唯一标准方式，前提是mypackage在PYTHONPATH或当前工作目录下可 import -
python mypackage/__main__.py✅ —— 可行，但此时__name__是'__main__'，而包内相对导入会全部失效（因为不是以包形式加载）
ZIP 包场景下 __main__.py 的不可替代性
当你把整个包打成 ZIP 文件分发时，__main__.py 是唯一能让 python archive.zip 正常启动的入口。ZIP 内部的目录结构必须保持平铺，且 __main__.py 必须在 ZIP 根路径下，否则解释器无法定位。
- ZIP 中不能有额外嵌套目录（如
archive.zip/mypackage/__main__.py不行） - 必须是
archive.zip/__main__.py，且同级还应有__init__.py才构成有效包 - 此时所有导入都基于 ZIP 文件为根，
sys.path[0]会自动设为该 ZIP 路径
真正容易被忽略的点在于：它不是“让包更好用”的锦上添花，而是 Python 解释器执行机制中一条刚性路径。一旦你希望用户用 python -m 启动你的包，__main__.py 就不是“建议添加”，而是“必须存在且位置精确”。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
