ComfyUI 导入工作流 JSON 时报节点版本差异相关错误，通常意味着工作流文件里记录的节点类型、输入字段或者自定义节点版本，与本地 ComfyUI 环境不完全一致。这类错误的表现形式很多，例如控制台提示 Unknown node type、前端弹出 Prompt outputs failed validation，或者某个节点一直显示红色。要彻底解决，需要先理解 ComfyUI 加载工作流时的节点注册和校验机制。
ComfyUI 的每个工作流 JSON 本质上是一个图数据，其中 nodes 数组保存所有节点实例，每个节点通过 type 字段声明自己的类名。加载时，ComfyUI 会拿这个 type 去当前环境已注册的节点表里查找，如果找不到就直接报节点不存在。即使类名存在，如果节点代码升级后修改了 INPUT_TYPES 里的字段名、字段类型或 required 约束，校验阶段也会报输入不匹配。因此，报错背后通常不是 JSON 文件坏掉，而是环境差异。
一、导入报错的核心原因：节点类型、版本与依赖三角关系
ComfyUI 的工作流文件可以拆成几层看：最外层包含 last_node_id、links、nodes 等字段，nodes 里每个对象描述一个节点。一个典型节点对象大致如下：
{
"id": 3,
"type": "KSampler",
"inputs": [{"name": "model", "type": "MODEL", "link": 1}],
"outputs": [{"name": "LATENT", "type": "LATENT", "links": [2]}],
"widgets_values": [1566802087000, "randomize", 20, 7.0]
}
这里的 type 就是节点类名。ComfyUI 核心节点和自定义节点都会在启动时向全局注册表登记自己的类名。如果 JSON 中的 type 在当前注册表里不存在，就会出现 node type not found 或类似错误。对于自定义节点，很多工作流依赖 ComfyUI-Manager 安装的第三方扩展，换一台机器或重装环境后，这些扩展没有安装，导入就会失败。
版本差异则更隐蔽。假设工作流里使用了 ControlNet 相关的某个节点，它在 1.0 版本里输入字段叫 image，到了 2.0 版本改成 positive 和 negative 两个条件输入。节点类名没变，但旧工作流传到新版本时会提示 missing input 或 value not in list。反过来，如果工作流是用新版生成的，旧节点代码也会因为多出的字段无法识别而报错。依赖包版本同样会造成类似问题，例如 diffusers 升级后部分自定义节点导入模块失败，节点直接加载不出来。
二、从报错信息中快速定位差异节点
ComfyUI 前端报错有时只显示 Prompt outputs failed validation，详细信息要回到启动 ComfyUI 的命令行窗口查看。终端里通常会出现类似以下内容：
Prompt outputs failed validation: - Node 12: unknown node type 'SeargeSDXL' - Node 15: input 'clip_skip' not found
从这段报错可以读出两个关键点：节点 12 的类名 SeargeSDXL 在当前环境没有注册；节点 15 的输入字段 clip_skip 不存在。前者优先考虑缺失自定义节点，后者优先考虑版本差异。拿到类名后，可以打开工作流 JSON 文件搜索该 type，查看对应节点周围的连接关系，判断它属于哪类扩展。
如果终端信息不够清晰，也可以用 Python 直接遍历 JSON，统计所有节点类型，并和当前 ComfyUI 已注册的节点列表做差集。下面脚本会输出工作流中使用了、但本地未注册的节点类型：
import json
import requests
with open('workflow.json', 'r', encoding='utf-8') as f:
data = json.load(f)
used_types = {node.get('type') for node in data.get('nodes', [])}
resp = requests.get('http://127.0.0.1:8188/object_info')
registered = set(resp.json().keys())
missing = used_types - registered
print('缺失节点类型:', missing)
这段脚本依赖 ComfyUI 已经启动并开放 API，127.0.0.1 是本地回环地址，不需要修改。运行后如果输出为空，说明节点都已注册，报错更可能来自输入字段或枚举值不匹配；如果输出若干类名，就按类名去安装对应扩展即可。
三、三种实操修复方案：安装、回退与直接改JSON
针对缺失节点，最直接的方式是通过 ComfyUI-Manager 的 Install Missing Custom Nodes 功能。启动 ComfyUI 后打开管理器，它会扫描工作流中用到的节点类型，并列出可以安装的扩展。如果没有管理器，可以手动到 custom_nodes 目录克隆对应仓库。例如缺少 SeargeSDXL 节点，通常在 ComfyUI 社区搜索 SeargeSDXL 即可找到仓库地址，克隆后重启 ComfyUI。
手动安装时还要注意依赖。很多自定义节点的 requirements.txt 里声明了特定版本的 Python 包，如果直接跳过依赖安装，节点可能导入失败，但报错信息会表现为模块缺失，而不是节点缺失。克隆仓库后，在对应目录执行以下命令：
cd custom_nodes/ComfyUI-SeargeSDXL pip install -r requirements.txt
如果确认节点已安装，但报的是字段不匹配，说明节点版本和工作流版本不一致。这时有两个方向：要么把节点版本回退到工作流生成时的版本，要么手动修改 JSON 适配当前节点。使用 Git 管理自定义节点时，回退非常方便。先查看节点的提交历史，找到更新时间与工作流创建时间接近的 tag 或 commit，然后执行：
cd custom_nodes/ComfyUI-AdvancedControlNet git log --oneline --decorate -5 git checkout v1.2.3 pip install -r requirements.txt
如果不方便回退，或者同一工作流中多个节点依赖不同版本，手动修改 JSON 会更灵活。核心思路是遍历 nodes，把旧类型名替换成新类型名，并把旧输入字段名映射成新字段名。下面脚本演示了把旧版 LatentUpscale 节点替换为 LatentUpscaleBy，并调整输入字段：
import json
with open('workflow.json', 'r', encoding='utf-8') as f:
data = json.load(f)
type_mapping = {'LatentUpscale': 'LatentUpscaleBy'}
field_mapping = {'upscale_method': 'method'}
for node in data.get('nodes', []):
if node.get('type') in type_mapping:
node['type'] = type_mapping[node['type']]
for link in node.get('inputs', []):
if link.get('name') in field_mapping:
link['name'] = field_mapping[link['name']]
with open('workflow_compat.json', 'w', encoding='utf-8') as f:
json.dump(data, f, indent=2)
这种方法适合节点内部逻辑基本一致、只是命名变化的情况。如果新版节点增加了必填输入，或者删除了某个输出类型，仅改字段名是不够的，可能需要重新连接节点或插入转换节点。因此修改前务必保留原始 JSON 备份，并在导入后逐节点检查连线是否正常。
四、建立兼容性检查流程，从源头减少导入失败
与其每次报错后被动修复，不如在导入前做一次轻量级检查。ComfyUI 提供了 /object_info 接口，可以返回所有已注册节点的输入、输出和参数结构。写一个脚本读取工作流 JSON，逐节点检查 type 是否存在，以及 inputs 里的字段名是否在当前节点定义的 required 或 optional 中。这样可以在导入前就发现大部分兼容性问题。
import json
import requests
with open('workflow.json', 'r', encoding='utf-8') as f:
nodes = json.load(f)['nodes']
info = requests.get('http://127.0.0.1:8188/object_info').json()
for node in nodes:
node_type = node.get('type')
if node_type not in info:
print('未注册节点:', node_type)
continue
required = info[node_type].get('input', {}).get('required', {})
optional = info[node_type].get('input', {}).get('optional', {})
all_fields = set(required) | set(optional)
for link in node.get('inputs', []):
if link.get('name') not in all_fields:
print('字段不匹配:', node_type, link.get('name'))
这段检查可以接到自己的导入流程里，也可以做成一个独立脚本。它会逐项列出未注册节点和输入字段不匹配项，比直接看前端报错更直观。对于团队协作或需要在多台机器之间迁移工作流的场景，建议把自定义节点目录用 Git 管理起来，并提交 requirements 锁定文件。每次更新节点后，先导出当前工作流，再用脚本跑一遍兼容性检查，确认无误再分发给其他人。
还应该注意 ComfyUI 本体版本。某些核心节点的行为会随版本升级变化，例如采样器、调度器枚举值在不同版本中可能新增或移除。工作流 JSON 里的 widgets_values 和节点类型虽然不变，但旧版 ComfyUI 可能无法识别新版新增的调度器名称。因此，迁移工作流时除了关注自定义节点，也要记录生成工作流时的 ComfyUI 版本。必要时可以同时固定 ComfyUI 本体和 custom_nodes 目录的 Git commit。