如何从零写出你的第一个 ComfyUI 自定义节点（新手完整指南）

如何从零写出你的第一个 ComfyUI 自定义节点新手完整指南【免费下载链接】ComfyUIThe most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface.项目地址: https://gitcode.com/GitHub_Trending/co/ComfyUIComfyUI 插件开发说穿了就是写 Python 节点把一段处理逻辑包装成可视化节点拖进工作流就能用。这篇指南带你从零写一个自定义节点——先跑通最小骨架再配参数、接外部 API最后过一遍性能与交付自检。读完你手里会有一个能实际运行的节点而不是一堆概念。任务一跑通你的最小可运行节点 你的第一步不是设计功能而是让一个什么都不做的节点出现在界面上。仓库里的 custom_nodes/example_node.py.example 就是最好的引子。理解它只需要抓住两个入口define_schema声明。告诉 ComfyUI 这个节点叫什么、放在哪个分类、有哪些输入输出。它是节点的说明书。execute执行。真正干活的地方接收输入张量返回输出。把样板剥掉骨架长这样每行都有注释from comfy_api.latest import ComfyExtension, io class MyFirstNode(io.ComfyNode): classmethod def define_schema(cls) - io.Schema: # 入口1声明ID、名称、输入输出 return io.Schema( node_idMyFirstNode, # 节点唯一ID连线类型由它决定 display_name我的第一个节点, # 界面上显示的名字 inputs[io.Image.Input(image)], outputs[io.Image.Output()], ) classmethod def execute(cls, image): # 入口2真正的处理逻辑 return io.NodeOutput(image) # 原样透传先跑通再说把它存进custom_nodes/目录参考示例文件末尾的comfy_entrypoint注册入口重启后在节点面板按分类名找到它。用仓库自带的input/example.png接一根线点 Queue Prompt——节点能跑通你就跨过了新手期最大的坎。任务二给节点配参数——把输入类型当配料节点能不能被用起来取决于参数配得好不好。ComfyUI 的输入类型就像配料按需抓几样配料作用适合场景io.Image图像张量0~1 浮点一切图像节点io.Int/io.Float整数 / 浮点可设min、max、step数量、强度等数值io.Combo下拉菜单options给选项列表模式选择io.Bool开关是否启用某功能io.String文本multilineTrue可多行提示词以智能图像增强为例一个能直接读懂的参数配置inputs[ io.Float.Input(strength, default1.5, min0.5, max3.0, step0.1), # 数值步进 io.Combo.Input(mode, options[对比度, 锐化, 智能], default智能), # 下拉 io.Bool.Input(preview, defaultFalse), # 开关 ], 小技巧给io.Float加display_modeio.NumberDisplay.slider界面上就变成滑块比手输数字顺手得多。官方输入参数可配项一览见下图default、min/max、lazy、placeholder都能在这里找到。写节点时的默认习惯数值给合理默认值、选项里把最常用的放第一个用户不改参数也能直接跑。任务三图像之外的素材音频与潜空间图像只是 ComfyUI 的一种素材。想处理别的东西换个输入输出类型即可套路完全一样。音频comfy_extras/nodes_audio.py 里的EmptyLatentAudio就是现成模板——输入只有seconds和batch_size两个参数输出是IO.Latent.Output()。潜空间latent是模型压缩后的中间表示音频和图像共用这一套机制。潜空间 / 条件io.Latent、io.Conditioning对应扩散模型的生成分支io.Model、io.Vae对应权重分支。你不需要现在就深入这里。记住一点就够了素材类型不同只换io.XXX.Input/Outputdefine_schemaexecute的写法不变。任务四按需计算参数减少无效执行ComfyUI 有执行缓存输入没变节点就不重复执行。但还有两个更细的问题要解决——问题 A有些输入根本不想算。比如节点有个输出调试信息开关开关关着时那些字符串、数值输入求值了也白求。用check_lazy_status解决classmethod def check_lazy_status(cls, print_to_screen): # 只有开关打开才要求系统去求值其余字段 if print_to_screen enable: return [int_field, string_field] return [] # 返回空列表 其余输入全部跳过把对应输入在 schema 里标上lazyTrue这个方法才能生效。问题 B输入没变但我想强制重跑。比如加载图片节点图片内容变了文件名却相同。用fingerprint_inputs解决——返回一个指纹字符串框架拿它和上次的值比较不同就重跑classmethod def fingerprint_inputs(cls, image, seed): # 图像形状或seed任一变化都触发重新执行 return f{image.shape}_{seed}两者分工check_lazy_status管算不算fingerprint_inputs管要不要再算一次。任务五接入外部 AI APIComfyUI 官方就内置了一整套第三方 API 节点目录 comfy_api_nodes/ 下apis/文件夹里躺着 Gemini、Luma、Tripo、ElevenLabs 等服务的集成代码是最值得抄的作业。API 节点和纯计算节点最大的区别在于要处理网络。四个关键点关键点解决什么问题常见做法密钥API Key 不能写死在代码里用隐藏输入如IO.Hidden.api_key_comfy_org或配置项传入异步网络请求耗时长不能卡死其他节点async def execute aiohttp 发请求错误429、超时、限流都要有交代捕获异常报出哪个服务、什么原因必要时重试进度生成一张图可能等 30 秒用户不能干瞪眼长任务里周期性上报进度前端显示进度状态异步部分的核心形态classmethod async def execute(cls, api_key, prompt): # async 让网络等待不阻塞工作流里其他节点 resp await session.post( endpoint, # 服务商提供的地址 headers{Authorization: fBearer {api_key}}, # 密钥走header json{prompt: prompt}, ) if resp.status ! 200: raise Exception(fAPI调用失败{await resp.text()}) # 明确报错 return io.NodeOutput(await resp.json()) # 解析结果返回写自己的 API 节点时直接打开comfy_api_nodes/apis/gemini.py对照着看密钥、重试、进度三处怎么写比看十篇文档都直观。任务六批量处理与显存优化ComfyUI 里一张图是一个 batch1 的张量一个 batch 就是多张。优化思路两条能批量就别循环不训练就别留梯度。对比一下处理同一批图像# 优化前逐张处理梯度开着中间张量堆在显存里 for i in range(images.shape[0]): out conv(images[i])# 优化后整个batch一次算完无梯度显存占用大幅下降 with torch.no_grad(): out conv(images) # 卷积等操作大多支持整批计算要点很短推理节点一律套torch.no_grad()能用向量化整批算的别写 Python for 循环。处理 4K 大图或视频帧时这两条能直接决定你的节点是能用还是会炸显存。任务七用自检清单验收你的节点节点写完只是完成 50%。交付前拿这份清单过一遍 ✅单一职责这个节点只做一件事增强抠图水印应该拆成三个节点命名清晰node_id稳定不随意改改了旧工作流会断display_name是人话默认值合理不填任何参数就能直接跑通提示友好数值参数给了min/max/tooltip报错信息说得出哪里错了、怎么办中文提示面向中文用户的display_name和选项文案是中文示例工作流仓库里附一份用到了你节点的工作流 JSON别人导入就能看效果对照 comfy_extras/ 里任何官方节点检查一遍参数都有默认值、注释齐全、单一职责——这就是别人愿意用的基线。下一步行动三个具体动作按顺序做克隆仓库git clone https://gitcode.com/GitHub_Trending/co/ComfyUI照着 custom_nodes/example_node.py.example 改成你自己的节点放进custom_nodes/重启验证它出现在面板里打开 comfy_extras/ 挑一个和你方向最近的官方节点比如做颜色就用nodes_color.py逐行读懂它的 schema 和 execute再回头改自己的交付前复制这份 checklist 自查- [ ] 最小骨架能跑通define_schema execute - [ ] 参数都有默认值min/max 合理 - [ ] 重参数场景用了 lazy check_lazy_status - [ ] 需要强制重跑时写了 fingerprint_inputs - [ ] 接 API密钥走配置、请求走 async、报错说人话、有进度反馈 - [ ] 推理逻辑包了 torch.no_grad()无无谓的 for 循环 - [ ] 附了一份示例工作流【免费下载链接】ComfyUIThe most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface.项目地址: https://gitcode.com/GitHub_Trending/co/ComfyUI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考