Python multiprocessing多进程worker未执行、map函数不触发问题排查

云原生阿岚

2026-8-28

问题原因

这个问题是Python multiprocessing 模块跨平台使用时的典型坑，核心诱因按出现概率从高到低排序如下：

spawn启动模式的环境/代码规范不满足
Windows全版本、macOS 从Python 3.8开始默认用spawn模式创建子进程（和Linux默认的fork模式逻辑完全不同）：spawn模式下子进程会启动全新的Python解释器，重新导入主脚本模块，要求所有传给worker执行的函数、自定义类必须定义在脚本顶层，不能在交互式环境（REPL、Jupyter、IDLE交互Shell）中直接运行代码——这类环境下定义的函数/类无法被子进程正常导入序列化，会导致worker启动失败，任务静默不执行，也不会抛出显眼的异常。
另外如果创建进程池、调用进程池方法的代码没有放在if __name__ == '__main__':保护块下，会触发子进程递归创建进程池的死锁问题，从你贴的代码看这部分写法是符合要求的。
输入文件列表为空，map阶段无任务可执行
你用glob.glob('*.py')匹配文件时，匹配的是运行脚本时的当前工作目录，不是脚本自身所在的目录：如果在IDE中运行，IDE默认工作目录可能是项目根目录；如果命令行运行时没有cd到脚本所在目录，都会导致glob匹配不到任何文件，传入pool.map的输入是空列表，自然不会触发一次file_to_words调用，也不会有任何日志输出。
子进程输出缓冲导致日志被吞，误以为函数未执行
多进程子进程的标准输出默认是块缓冲模式，print内容不会立刻输出到终端：如果worker执行速度快，缓冲区没攒满进程就退出，print的内容会被直接丢弃；部分IDE的多进程输出捕获逻辑有缺陷，也会导致子进程日志无法显示在控制台。
进程池未正确关闭导致任务异常终止
你的代码中在SimpleMapReduce.__init__里创建进程池后，从来没有调用close()/join()释放资源，部分平台下进程池对象被垃圾回收时会直接终止子进程，导致任务还没执行就退出。

排查&修复方案

按以下步骤逐一排查即可解决问题：

先确认输入文件列表非空
在glob.glob行下方加一行打印，确认匹配到了目标文件：
```
input_files = glob.glob('*.py')
print(f"待处理文件列表：{input_files}", flush=True)
```
如果输出为空列表，把glob路径改成脚本所在目录的绝对路径，或者运行时先cd到脚本存放目录再执行。
不要在交互式环境运行脚本
把代码存为独立的.py文件，打开系统命令行（cmd/PowerShell/终端），cd到脚本所在目录后用python 脚本文件名.py执行，排除交互式环境的序列化问题。

强制刷新输出缓冲
给所有子进程里的print语句加上flush=True参数，避免日志被缓冲吞掉：

print("any message", flush=True)
print('{} reading {}'.format(
    multiprocessing.current_process().name, filename), flush=True)

补上进程池的资源释放逻辑
修改SimpleMapReduce类，在任务执行完成后正确关闭进程池，避免异常终止：

def __call__(self, inputs, chunksize=1):
    map_responses = self.pool.map(
        self.map_func,
        inputs,
        chunksize=chunksize,
    )
    partitioned_data = self.partition(
        itertools.chain(*map_responses)
    )
    reduced_values = self.pool.map(
        self.reduce_func,
        partitioned_data,
    )
    # 关闭进程池，等待所有任务完成
    self.pool.close()
    self.pool.join()
    return reduced_values

（可选，仅Linux/macOS适用）如果是在类Unix系统上运行，可以显式指定用fork模式启动进程，规避spawn模式的各种限制，在if __name__ == '__main__':块最开头加一行：
```
multiprocessing.set_start_method('fork', force=True)
```

按以上步骤修改后，即可正常看到worker的执行日志，词频统计逻辑也会正常运行。

内容的提问来源于stack exchange，提问作者Little