小周那天写了一个数据清洗脚本，既能当命令行工具用，又能被其他模块导入调用。他的思路很简单：在文件末尾写一段测试代码，跑一下看看效果。
# clean_data.py
def clean(records):
return [r.strip() for r in records if r]
# 测试代码
records = [" Alice ", "", " Bob ", " "]
print(clean(records))
本地跑 python clean_data.py，输出 ['Alice', 'Bob']，没问题。
后来同事写了一个报表模块，需要复用这个 clean 函数：
# report.py
from clean_data import clean
data = [" x ", " y "]
print(clean(data))
跑 python report.py，输出是这样的：
['Alice', 'Bob']
['x', 'y']
第一行是 clean_data.py 里的测试代码被意外执行了。小周很郁闷：“我只是导入一个函数，怎么把别人的测试代码也跑了一遍？”
他上网查了一下，几乎所有教程都在说：“把测试代码放到 if __name__ == "__main__": 里面。”他照做了：
# clean_data.py
def clean(records):
return [r.strip() for r in records if r]
if __name__ == "__main__":
records = [" Alice ", "", " Bob ", " "]
print(clean(records))
再跑 report.py，这次只输出了 ['x', 'y']，测试代码没执行。问题解决了，但小周心里犯嘀咕：“__name__ 和 __main__ 到底是什么？为什么加了这个判断，代码就不跑了？”
这个问题的答案，是 Python 模块系统里最基础、也最容易被忽略的一个机制：每个模块都有一个 __name__ 属性，它的值取决于这个模块是“被直接运行”还是“被导入”。
先看一个最直观的实验
新建一个文件 demo.py：
print(f"__name__ 的值是: {__name__}")
直接运行：
$ python demo.py
__name__ 的值是: __main__
再新建一个文件 other.py，导入 demo：
# other.py
import demo
运行 other.py：
$ python other.py
__name__ 的值是: demo
同一个文件，同一个 print 语句，直接运行时 __name__ 是 "__main__"，被导入时 __name__ 是 "demo"。
这就是整个机制的核心：**__name__ 是 Python 自动设置的模块属性，直接运行的模块，它的 __name__ 是 "__main__"；被导入的模块，它的 __name__ 是模块名。**
用一个生活场景来理解。你有一个员工，名叫“张三”。
当张三在自己家里时，家人叫他“张三”。
当张三在公司时，同事叫他“张经理”。
同一个人，在不同的环境里，有不同的称呼。__name__ 就是模块的“称呼”：在自己家里（直接运行）叫 "__main__"，在公司里（被导入）叫模块名。
直接运行 vs 被导入：两种身份
Python 文件有两种使用方式。
方式一：直接运行。 python clean_data.py。这时候 Python 把 clean_data.py 当作主程序，它的 __name__ 被设为 "__main__"。
方式二：被导入。 在另一个文件里写 import clean_data，或者在 report.py 里写 from clean_data import clean。这时候 Python 把 clean_data.py 当作一个模块加载，它的 __name__ 被设为 "clean_data"（模块名）。
# clean_data.py
print(f"模块名: {__name__}")
def clean(records):
return [r.strip() for r in records if r]
直接运行：
$ python clean_data.py
模块名: __main__
被导入：
$ python -c "import clean_data"
模块名: clean_data
这个区别是 Python 刻意设计的。它让同一个文件可以有两种行为：作为主程序时执行某些代码，作为模块被导入时不执行那些代码。
if name == "main": 到底在判断什么？
现在再看这行经典的代码：
if __name__ == "__main__":
# 这里的代码只在直接运行时执行
main()
它的意思是：如果当前模块是直接运行的（__name__ 是 "__main__"），就执行下面的代码；如果是被导入的，就跳过。
这个判断的本质是“身份检查”：我是主程序，还是被导入的模块？
# clean_data.py
def clean(records):
return [r.strip() for r in records if r]
if __name__ == "__main__":
# 只有 python clean_data.py 才会执行
print("这是直接运行")
print(clean([" a ", " b "]))
else:
# 被导入时执行
print("这是被导入")
直接运行 python clean_data.py：
这是直接运行
['a', 'b']
被 report.py 导入时：
这是被导入
if __name__ == "__main__": 不是一个特殊语法，它就是一个普通的 if 判断。__name__ 是一个普通的字符串变量，"__main__" 是一个普通的字符串常量。两者相等时，执行 if 块里的代码。
坑一：不写 if name == "main"，测试代码被导入时执行
这就是小周踩的坑。
# clean_data.py
def clean(records):
return [r.strip() for r in records if r]
# 没有 if 保护
records = [" Alice ", "", " Bob "]
print(clean(records))
任何导入 clean_data 的模块，都会触发这段代码。轻则多打印几行，重则执行了不该执行的操作，比如删文件、发请求、改数据库。
# report.py
from clean_data import clean
# 导入的瞬间，clean_data.py 里的测试代码就执行了
解决方案就是把测试代码放进 if __name__ == "__main__": 里。
坑二：把 main 函数写在 if 块外面
有些人会这样写：
def main():
records = [" Alice ", "", " Bob "]
print(clean(records))
# 直接调用，没有 if 保护
main()
这和不写 if 是一样的，main() 在导入时就会被调用。
正确的写法：
def main():
records = [" Alice ", "", " Bob "]
print(clean(records))
if __name__ == "__main__":
main()
main() 只在直接运行时被调用。被导入时，main 函数定义存在，但不会执行。
坑三：以为 name 是模块名
有些人以为 __name__ 永远是模块名，所以在代码里这样写：
# utils.py
if __name__ == "utils":
print("这是 utils 模块")
这段代码永远不会执行。因为直接运行 utils.py 时，__name__ 是 "__main__"，不是 "utils"。被导入时，__name__ 是 "utils"，但 if 块里的代码是给“直接运行”准备的，这时候不应该执行。
__name__ 的值只有两种可能：直接运行时是 "__main__"，被导入时是模块名。不要假设它是模块名。
坑四：在多进程/多线程里重新导入
multiprocessing 在 Windows 上使用 spawn 方式启动子进程时，会重新导入主模块。如果没有 if __name__ == "__main__": 保护，主模块的顶层代码会在每个子进程里重新执行一遍。
# 错误写法
import multiprocessing
def worker(x):
return x * 2
# 没有 if 保护
results = [worker(i) for i in range(10)]
print(results)
# 创建进程池
with multiprocessing.Pool() as pool:
pool.map(worker, range(10))
在 Windows 上运行，每个子进程都会重新执行 results = [...] 和 print(results)，输出混乱，甚至可能递归创建进程。
正确写法：
import multiprocessing
def worker(x):
return x * 2
def main():
with multiprocessing.Pool() as pool:
results = pool.map(worker, range(10))
print(results)
if __name__ == "__main__":
main()
main() 只在主进程里执行一次，子进程导入模块时不会触发。
这是 if __name__ == "__main__": 在 Windows 多进程场景下的硬性要求，不写会直接出错。
坑五：用 name 做相对导入
__name__ 还可以用来做相对导入，但这很容易出错：
# package/module.py
if __name__ == "__main__":
from . import sibling # 直接运行时，相对导入会失败
直接运行 python package/module.py 时，__name__ 是 "__main__"，模块没有包上下文，相对导入 . 会报错：
ImportError: attempted relative import with no known parent package
正确的做法是用绝对导入，或者用 python -m package.module 运行：
$ python -m package.module
这时候 __name__ 是 "__main__"，但模块有包上下文，相对导入能正常工作。
坑六：__name__ 的值可能被修改
__name__ 是一个普通的模块属性，可以被修改：
# some_module.py
print(__name__) # "some_module"
__name__ = "hacked"
print(__name__) # "hacked"
但修改它会影响 if __name__ == "__main__" 的判断。正常情况下没有人会这么做，但如果你在调试时手动改了 __name__，可能会遇到意外的行为。
__name__ 应该被视为只读属性，不要修改它。
那 main 是什么？
__main__ 有两个含义，容易混淆。
含义一：__name__ 的值。 当一个模块被直接运行时，它的 __name__ 属性被设为字符串 "__main__"。
含义二：__main__ 模块。 Python 有一个特殊的模块叫 __main__，它是程序的入口模块。直接运行的脚本，它的内容会被加载到 __main__ 模块里。
# demo.py
import __main__
print(__main__.__name__) # "__main__"
print(__main__ is __import__(__name__)) # True
在 demo.py 里，__main__ 模块就是 demo.py 自己。__main__.__name__ 是 "__main__"，__main__.__file__ 是 demo.py 的路径。
在 report.py 里导入 clean_data 时：
# report.py
import __main__
print(__main__.__name__) # "__main__"，但这是 report.py 自己
print(__main__.__file__) # "report.py"
__main__ 模块始终是“主程序”，不管你在哪个模块里访问它。
一个常见的结构：main 函数 + 入口判断
实际项目里最常见的写法是：
# app.py
import sys
import logging
logger = logging.getLogger(__name__)
def parse_args():
# 解析命令行参数
...
def run(config):
# 主逻辑
...
def main():
args = parse_args()
config = load_config(args.config)
run(config)
if __name__ == "__main__":
main()
这个结构的好处是：
第一，main() 可以被测试代码直接调用，不需要通过命令行。
# test_app.py
from app import main
def test_main():
main() # 直接调用，不会触发命令行解析
第二，被导入时不会执行任何副作用。parse_args、run、main 都只是定义，不会自动执行。
第三，入口清晰。看文件末尾就知道这个模块怎么运行。
什么时候需要 if name == "main"？
判断标准：
文件会被其他模块导入：需要。否则导入时测试代码会执行。
文件只作为脚本直接运行，不会被导入：不需要。但加上也无害，而且是一个好习惯。
文件里有测试代码、演示代码、命令行入口：需要。这些代码只在直接运行时执行。
文件是纯函数/类库，没有任何顶层副作用：不需要。但加上 if 块可以放一些自测代码。
使用 multiprocessing 且需要跨平台：必须。Windows 的 spawn 模式要求入口保护。
使用 python -m 运行包内模块：需要。__name__ 是 "__main__"，但模块有包上下文。
回到小周的故事
小周最终的 clean_data.py 是这样的：
def clean(records):
return [r.strip() for r in records if r]
def main():
records = [" Alice ", "", " Bob ", " "]
print(clean(records))
if __name__ == "__main__":
main()
report.py 导入 clean 时，只拿到了函数定义，测试代码不会执行。直接运行 clean_data.py 时，main() 会执行，方便他调试。
他后来在团队文档里写了一条：“每个会被导入的 Python 文件，测试代码和入口逻辑都要放在 if __name__ == "__main__": 里面。__name__ 在直接运行时是 '__main__'，被导入时是模块名。这个判断的本质是检查‘我是主程序还是被导入的模块’。多进程在 Windows 上必须写这个判断，否则子进程会重复执行主模块的顶层代码。”
这个机制看起来简单，但真到写代码的时候，很多人会随手在文件末尾写几行测试代码，然后在被导入时发现多了一堆意外的输出。或者用 multiprocessing 时没加保护，在 Windows 上跑出递归创建进程的诡异 bug。
记住那个员工称呼的比喻：同一个人，在家叫“张三”，在公司叫“张经理”。同一个文件，直接运行叫 "__main__"，被导入叫模块名。if __name__ == "__main__": 就是在问：“我现在是在家里，还是在公司？”
主入口本身不难，难的是想清楚“这个文件会不会被导入、导入时哪些代码不该执行”。想清楚了，__name__ 和 __main__ 就不再是坑，而是两个让模块既能独立运行、又能被复用的工具。
