根本原因是网络连通性或初始化参数不一致；需确保所有rank双向直连master地址、参数完全一致、nccl网卡配置正确，并用all-reduce验证而非仅依赖init成功。
为什么dist.init_process_group总卡住或报超时错误？
根本原因通常是网络连通性或初始化参数不一致，而不是代码写错了。PyTorch分布式默认用TCP后端时，所有rank必须能双向直连init_method指定的master地址和端口；用file://时则依赖共享文件系统且各进程需有相同路径权限。常见现象是某个rank卡在init_process_group调用处不动，或抛出RuntimeError: Timed out initializing process group。
- 检查
MASTER_ADDR是否为所有节点可解析的真实IP（不能是localhost或127.0.0.1） - 确认
MASTER_PORT未被防火墙拦截，且未被其他进程占用（可用netstat -tuln | grep PORT验证） - 所有rank必须使用完全相同的
init_method、world_size、rank、backend（如nccl或gloo） - NCCL后端下还需确保
NCCL_SOCKET_IFNAME设为实际通信网卡名（如eth0），否则可能走错接口
用file://方式绕过网络问题是否可靠？
适用于单机多卡或已挂载NFS的集群，但对文件系统一致性要求高。它本质是靠一个临时文件做信号同步，一旦任一进程写入失败或读取延迟，就会超时。
- 路径必须是所有rank都可读写的绝对路径，例如
file:///mnt/shared/.torch_dist_init（注意三个斜杠） - 确保目录存在且权限开放：
chmod 777 /mnt/shared，否则部分rank会因PermissionError静默失败 - 每次运行前手动清空该文件，避免残留导致
RuntimeError: File exists - 不适用于Windows或某些容器环境（如无共享存储的K8s Pod）
timeout参数调大就能解决吗？
可以缓解但治标不治本。默认timeout是30分钟（timedelta(minutes=30)），但盲目加到几小时只会掩盖真实问题，比如某台机器GPU不可用、CUDA上下文初始化失败，这些错误会被timeout掩盖。
- 调试阶段建议先设为短超时：
timeout=timedelta(seconds=30)，快速暴露卡点 - 仅当确认网络/配置无误后再适度延长，例如
timedelta(minutes=5) - NCCL后端还受
NCCL_BLOCKING_WAIT=1影响——设为1时会把NCCL内部超时也暴露为Python异常，便于定位 - 永远不要依赖延长timeout代替连通性检查
如何快速验证分布式初始化能否真正跑通？
写一个最小可执行片段，在每个rank上打印日志并做一次all-reduce，比只看init是否返回更可靠。
import torch
import torch.distributed as dist
import os
os.environ['MASTER_ADDR'] = '192.168.1.100'
os.environ['MASTER_PORT'] = '29500'
dist.init_process_group(backend='nccl', world_size=2, rank=int(os.environ['RANK']))
print(f"Rank {dist.get_rank()} initialized")
x = torch.tensor([dist.get_rank()]).cuda()
dist.all_reduce(x)
print(f"Rank {dist.get_rank()} got sum: {x.item()}")
dist.destroy_process_group()
如果某rank没打印第一行，说明卡在init；如果卡在all_reduce，说明NCCL通信层有问题（比如GPU拓扑或IB/RoCE配置）。这种验证比单纯“不报错”更有意义。
最容易被忽略的是：不同rank的CUDA_VISIBLE_DEVICES设置不一致，或者某张卡正被其他进程占用，此时init_process_group看似成功，但后续cuda()操作会静默失败或hang住。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
