ComfyUI 升级 v0.4.0 踩坑记录：解决 TypeError: QM_Queue.task_done() 报错

记录于：2025年12月17日

ComfyUI version: 0.4.0
暂未适配v0.4.0的队列管理器旧版插件

comfyui_queue_manager
另一个可尝试替代的队列管理器

ac-comfyui-queue-manager
Comfy.ICU 队列管理器介绍

ComfyUI 升级 v0.4.0 踩坑记录：解决 TypeError: QM_Queue.task_done() got an unexpected keyword argument 'process_item' 报错

前言

最近 ComfyUI 发布了 v0.4.0 大版本更新。我原本还在用比较老的版本（大概是 v0.3.64 左右），经过尝试和搜索得知，只有该版本（v0.4.0 ）才支持 Z-Image 的相关工作流，心血来潮想升级一下源代码部署版。结果这一升级，直接把环境搞崩了。

启动正常，但在点击"Queue Prompt"开始生图时，控制台直接红字刷屏，任务死活跑不起来。经过一番排查（和求助 AI 大佬），终于搞定了。特此记录，希望能帮到遇到同样报错的小伙伴。

报错现象

ComfyUI 启动后，后台出现自动恢复任务或手动点击生成时，控制台抛出如下核心错误：

启动后日志中报错

复制代码

Exception in thread Thread-27 (prompt_worker):
Traceback (most recent call last):
  ...
  File "H:\PythonProjects1\Win_ComfyUI\main.py", line 236, in prompt_worker
    q.task_done(item_id,
TypeError: QM_Queue.task_done() got an unexpected keyword argument 'process_item'

症状总结：

界面能打开，节点能连。
一点生成，进度条不走。
后台报错提示 task_done() 函数多了一个不认识的参数 process_item。

原因分析

这个报错的根本原因是：ComfyUI 的"核心代码"与"插件/依赖文件"版本不匹配（Version Mismatch）。

通俗点说，就是出现了"跨频道聊天"：

发送者（main.py） ：我升级到了 v0.4.0，不仅告诉你要"完成任务"，还顺便传了一个新参数 process_item 让你处理敏感数据。
接收者（旧版 execution.py 或旧版插件） ：我还停留在 v0.3.x 时代，我只知道"完成任务"，你给我的这个 process_item 是什么鬼？我不认识，直接报错！

在我（以及很多手动升级的用户）的案例中，主要有两个"拦路虎"：

官方核心文件没有同步更新完全： execution.py 还是旧的。
第三方插件搞事情： 安装过 ComfyUI-Queue-Manager 插件，它接管了系统队列，但它的代码还没适配 v0.4.0。

解决方案（三步走）

如果你也遇到了这个问题，请按顺序执行以下操作。注意：这三个操作缺一不可！

第一步：确保 main.py 是最新的

既然要升级 v0.4.0，首先要确保启动脚本是最新的。

操作： 从 ComfyUI 官方 GitHub 仓库下载最新的 main.py 覆盖根目录文件。
这一步通常是我们升级的开始，也是导致报错的诱因，但它是必须的。

第二步：同步更新 execution.py（核心修复）

很多时候我们只覆盖了 main.py，却忘了它的"搭档"文件。

操作： 从 ComfyUI 官方 GitHub 仓库下载最新的 execution.py，替换 ComfyUI 根目录下的同名文件。
作用： 确保 ComfyUI 原生的队列系统能听懂 main.py 发出的新指令。

第三步：移除不兼容的队列插件（关键修复）

这是最容易被忽视的一点。报错信息里的 QM_Queue 其实暴露了是 Queue Manager 插件在报错。

操作： 进入 custom_nodes 文件夹，找到 comfyui_queue_manager（或类似名字），将其删除或移出该目录。
作用： 这个插件目前（截止2025年12月）尚未适配 v0.4.0 的 API。删除它，让 ComfyUI 回归使用官方原生的队列系统。

针对以上三步操作的疑问解惑：

"这三个操作（更新main.py、更新execution.py、删除Queue Manager插件），哪些是有效的？"

答案是：这是一个"组合拳"，其中两个是决定性的修复步骤，一个是必要的前提。

更新 main.py ：这是必要前提 ，也是诱因。是因为您更新了它（为了升级到 v0.4.0），它开始发送新指令（process_item），才暴露了后面两个旧文件/旧插件接不住招的问题。
更新 execution.py ：这是核心修复之一 。如果不更新它，就算删了插件，ComfyUI 原生的队列也会因为接不住 process_item 而报错。
删除 comfyui_queue_manager ：这是关键修复之二。这个插件"劫持"了队列系统，但代码太老。如果不删它，就算您更新了所有官方文件，这个插件依然会挡在中间报错。

提示： 以后等该插件作者更新修复后，可以再重新安装回来。
重点同步更新这两个文件
然后删除旧版的问题插件

复盘总结

解决完上述三步后，重启 ComfyUI，世界清静了，生图丝般顺滑。

回顾这次排查，关于**"哪个操作才是有效的？"**，结论如下：

更新 main.py ：这是发起者。不更新它就没法用 v0.4.0 的新功能，但只更新它会导致报错。
更新 execution.py ：这是基础。必须更新它，官方核心逻辑才能闭环。
删除 Queue Manager ：这是排雷。如果保留这个旧插件，它会拦截系统调用并报错，导致前两步的更新"白费"。

给大家的建议：

ComfyUI 的版本更新（尤其是 v0.4.0 这种大版本）往往伴随着底层 API 的变动。如果手动更新太麻烦，建议使用 GitHub Desktop 安全地更新整个项目文件，或者使用秋叶整合包等工具进行全量更新，尽量避免"只替换这一个文件试试"的操作，很容易导致这种版本分裂的问题。
在 v0.4.0 版让 ComfyUI 回归使用官方原生的队列系统

希望这篇博客能帮到大家！