Python：__main__.py 文件详解

在 Python 项目开发中，__main__.py 是一个特殊的模块文件，它决定了当包或模块以入口程序运行时，Python 会执行什么代码。

理解 __main__.py 的作用，有助于我们构建可执行的 Python 包、组织项目结构，以及为代码提供统一的运行入口。

一、__main__.py 的作用

在两种情况下，Python 会执行 __main__.py 中的代码。

（1）以包运行

python -m package_name

比如，当你运行

python -m my_package

my_package

（2）以 ZIP 压缩包运行

python my_archive.zip

如果一个 ZIP 文件的根目录中包含 __main__.py，Python 会将该 ZIP 当作可执行程序运行，并执行 __main__.py。

核心作用：

• 作为程序入口，集中定义项目启动逻辑。

• 避免在包外部直接引用内部文件启动程序。

• 让包既能被导入（作为库），又能直接运行（作为程序）。

二、基本示例

项目结构：

└── core.py

__main__.py 内容示例：

    run_app()

core.py 内容示例：

    print("应用已启动！")

运行方式：

python -m my_package

输出：

应用已启动！

三、与 if __name__ == "__main__" 的区别

很多人会混淆 __main__.py 与 if __name__ == "__main__"：

简单来说：

• 单文件脚本：用 if __name__ == "__main__"。

• 可运行的包：用 __main__.py。

四、__main__.py 的常见用途

（1）提供命令行接口（CLI）

很多 Python 工具包（如 pip、pytest）在 __main__.py 中实现 CLI 逻辑，让用户可以直接运行：

python -m pip install requests

示例：

    sys.exit(main())

（2）作为应用的启动文件

在大型项目中，将所有启动逻辑集中放在 __main__.py：

    start_server()

（3）ZIP 应用打包

Python 允许将项目打包成 ZIP 并直接运行：

python app.zip

my_package/__main__.py 会作为入口执行。

从 Python 3.5 开始，可以使用 zipapp 模块来创建可执行的 zip 文件：

python app.zip

或者：

python app.pyz

这种技术常用于分发 Python 命令行工具和应用程序。

五、最佳实践

（1）保持简洁

__main__.py 中只放入口逻辑，避免直接写大量业务代码。建议将核心逻辑放在独立模块中，便于复用。

（2）明确命令行参数解析

如果包作为 CLI 工具，建议使用 或 等库进行参数解析：

print(f"你好，{args.name}！")

（3）兼容被导入的情况

尽管 __main__.py 主要用于直接运行，但它依然可以被 import，因此要避免执行不必要的逻辑。

“点赞有美意，赞赏是鼓励”