Python 3 教程

Python __name__ 与 __main__

lichongyang
6 min read 1,962

在 Python 中，__name__ 和 '__main__' 的组合（即 if __name__ == '__main__':）是 Python 编程中最经典、最重要的惯用法之一。

一句话总结它的核心作用：判断当前 Python 文件是被“直接运行”的，还是被其他文件“作为模块导入”的。

下面我将从底层原理、代码演示、核心价值到最佳实践，为你彻底讲透这个知识点。

一、 核心原理：__name__ 到底是什么？

__name__ 是 Python 的一个内置全局变量（前后有双下划线，称为“魔术变量”）。当 Python 解释器读取一个源文件时，它会在执行文件中的代码之前，自动为这个文件设置 __name__ 的值。

它的值只有两种情况：

  1. 直接运行该文件：
    如果你在终端执行 python my_script.py，Python 会将该文件的 __name__ 设置为字符串 '__main__'。
  2. 被其他文件导入：
    如果另一个文件执行了 import my_script，Python 会将 my_script.py 的 __name__ 设置为它的模块名（即 'my_script'，不带 .py 后缀）。

二、 直观代码演示

我们创建两个文件来观察 __name__ 的变化。

文件 1：calculator.py (作为模块)

纯文本
# calculator.py

print(f"👉 [加载时] calculator.py 的 __name__ 值是: '{__name__}'")

def add(a, b):
    return a + b

# 核心判断
if __name__ == '__main__':
    print("✅ [执行时] calculator.py 是被直接运行的！")
    print("测试结果:", add(2, 3))
else:
    print("⚠️ [执行时] calculator.py 是被其他文件导入的！")

文件 2：main_app.py (主程序)

纯文本
# main_app.py

print(f"👉 [加载时] main_app.py 的 __name__ 值是: '{__name__}'")

import calculator  # 导入上面的模块

print("在 main_app 中调用加法:", calculator.add(10, 20))

运行结果对比：

场景 A：直接运行 calculator.py

纯文本
$ python calculator.py
👉 [加载时] calculator.py 的 __name__ 值是: '__main__'
✅ [执行时] calculator.py 是被直接运行的！
测试结果: 5

场景 B：运行 main_app.py (导入 calculator)

纯文本
$ python main_app.py
👉 [加载时] main_app.py 的 __name__ 值是: '__main__'
👉 [加载时] calculator.py 的 __name__ 值是: 'calculator'
⚠️ [执行时] calculator.py 是被其他文件导入的！
在 main_app 中调用加法: 30

三、 为什么必须要有这个判断？（核心价值）

如果不加 if __name__ == '__main__':，会导致严重的 “副作用”（Side Effects）。

假设 calculator.py 没有这个判断，且末尾直接写了测试代码：

纯文本
# 糟糕的 calculator.py
def add(a, b): return a + b

print("正在测试加法:", add(2, 3)) # 👈 顶层代码，没有缩进

当你在 main_app.py 中 import calculator 时，这行测试代码会被立即执行并打印出来，污染了主程序的输出。

更危险的副作用包括：

  • 意外发起网络请求或数据库连接。
  • 意外修改了全局配置文件。
  • 意外启动了 Web 服务器（如 Flask/FastAPI 的 app.run()）。

if __name__ == '__main__': 就像一个安全阀，确保测试代码或启动代码只在“直接运行”时触发，而在“被导入”时保持静默。

四、 现代 Python 最佳实践模板

在实际工程中，我们通常不会把执行逻辑直接写在 if 语句块里，而是封装成一个 main() 函数。这样做的好处是：变量作用域更清晰，且方便其他模块复用或进行单元测试。

纯文本
import sys
import logging

# 1. 定义业务逻辑函数
def process_data(file_path: str):
    print(f"正在处理文件: {file_path}")
    # ... 复杂的业务逻辑 ...

# 2. 定义主入口函数
def main():
    # 可以在这里解析命令行参数
    if len(sys.argv) < 2:
        print("用法: python script.py <file_path>")
        sys.exit(1)

    file_path = sys.argv[1]
    process_data(file_path)

# 3. 安全阀：仅在直接运行时执行 main()
if __name__ == '__main__':
    # 可以在这里配置仅在直接运行时才生效的日志级别等
    logging.basicConfig(level=logging.INFO)
    main()

五、 进阶知识：__main__.py 文件

除了 __name__ == '__main__' 这个变量，Python 还有一个特殊的文件名：__main__.py。

如果你有一个包（文件夹），并且在其中放置了一个名为 __main__.py 的文件，你就可以直接运行整个包。

目录结构：

纯文本
my_package/
    ├── __init__.py
    ├── core.py
    └── __main__.py   # 👈 特殊文件

__main__.py 的内容：

纯文本
# my_package/__main__.py
print("正在启动 my_package 的命令行工具...")
from . import core
core.run()

运行方式：
此时，你不需要指定具体的 .py 文件，只需使用 -m (module) 参数运行包名：

纯文本
python -m my_package

注：这在开发命令行工具（CLI）或大型项目（如 python -m venv 或 python -m http.server）时非常常见。

总结

  • __name__ 是 Python 自动设置的内置变量。
  • 直接运行文件时，它是 '__main__'；被导入时，它是模块名。
  • if __name__ == '__main__': 是防止模块被导入时产生意外副作用的标准安全机制。
  • 最佳实践是将执行逻辑封装在 main() 函数中，并在该判断下调用它。

如果你在代码中遇到了与导入相关的奇怪行为（比如代码莫名其妙被执行了两次），99% 的情况都是因为缺少或误用了这个判断。有其他疑问随时问我！

Written by lichongyang

View all posts

You might also like