ComfyUI自定义节点开发指南：从零构建你的专属AI工具链
1. 为什么需要自定义ComfyUI节点？
第一次用ComfyUI做AI绘画时，我就被它灵活的节点式操作吸引了。但用着用着发现一个问题：官方提供的节点虽然强大，但总有些特殊需求无法满足。比如想给生成的图片自动打水印、批量处理文件夹里的图片、或者接入自己训练的特殊模型，这时候就需要开发自定义节点了。
自定义节点就像是给ComfyUI安装"外挂"，让它具备原本没有的能力。我去年给电商公司做产品图生成系统时，就开发过自动添加产品参数的节点，把商品SKU、价格等信息直接合成到图片上，省去了后期PS的麻烦。这种定制化功能用官方节点根本实现不了。
2. 开发环境准备
2.1 基础软件安装
开发ComfyUI节点需要准备以下工具，我用的是Windows 11系统，其他系统也大同小异：
- Python 3.10+：建议用Miniconda管理环境，避免版本冲突。我习惯创建一个专门的环境：
conda create -n comfydev python=3.10 conda activate comfydev- Git：用来下载ComfyUI源码和示例项目。如果没安装，在conda环境里运行：
conda install git- 代码编辑器：VS Code或PyCharm都行，我个人更喜欢VS Code的轻量化，装上Python插件就能直接调试。
2.2 ComfyUI源码获取
直接从GitHub克隆最新代码：
git clone https://github.com/comfyanonymous/ComfyUI.git cd ComfyUI pip install -r requirements.txt建议把代码放在固态硬盘上，我第一次开发时放在机械硬盘，启动速度慢了近3倍。现在我的项目结构是这样的：
D:\AI_Projects\ ├── ComfyUI/ # 主程序 └── custom_nodes/ # 自定义节点目录3. 第一个Hello World节点
3.1 创建节点文件
在custom_nodes文件夹下新建hello_world.py，这是最简单的节点模板：
import torch from comfy.sd import CLIP from nodes import SaveImage class HelloWorld: @classmethod def INPUT_TYPES(cls): return { "required": { "text": ("STRING", {"default": "Hello World!"}), } } RETURN_TYPES = ("STRING",) FUNCTION = "do_action" CATEGORY = "custom" def do_action(self, text): print(f"Received: {text}") return (text,) NODE_CLASS_MAPPINGS = { "HelloWorld": HelloWorld } NODE_DISPLAY_NAME_MAPPINGS = { "HelloWorld": "Hello World Node" }这个节点接收一个文本输入，原样输出到控制台。关键点：
INPUT_TYPES：定义输入参数RETURN_TYPES：声明输出类型FUNCTION：指定处理函数CATEGORY：决定节点在UI中的分类位置
3.2 测试运行
启动ComfyUI后，右键菜单里就能看到新增的"custom"分类下的Hello World节点。连上调试器后，我在VS Code里设置了断点，可以实时观察变量变化。
第一次运行时我遇到了ModuleNotFoundError，原因是没把custom_nodes目录添加到Python路径。解决方法是在启动脚本前加上：
import sys sys.path.append("D:/AI_Projects/custom_nodes")4. 开发实用功能节点
4.1 图片水印节点
下面这个实战案例是我给摄影工作室开发的批量水印工具：
from PIL import Image, ImageDraw, ImageFont import numpy as np import torch import os from nodes import PreviewImage class WatermarkNode: def __init__(self): self.font = ImageFont.truetype("arial.ttf", 36) @classmethod def INPUT_TYPES(cls): return { "required": { "images": ("IMAGE",), "text": ("STRING", {"default": "Sample Watermark"}), "opacity": ("FLOAT", {"default": 0.5, "min": 0, "max": 1}), } } RETURN_TYPES = ("IMAGE",) FUNCTION = "apply_watermark" CATEGORY = "image/postprocessing" def apply_watermark(self, images, text, opacity): batch_size = images.shape[0] results = [] for i in range(batch_size): img = 255. * images[i].cpu().numpy() img = Image.fromarray(np.clip(img, 0, 255).astype(np.uint8)) # 创建水印层 watermark = Image.new("RGBA", img.size) draw = ImageDraw.Draw(watermark) # 计算文字位置（右下角） text_width, text_height = draw.textsize(text, self.font) x = img.width - text_width - 20 y = img.height - text_height - 20 # 绘制半透明文字 draw.text((x, y), text, font=self.font, fill=(255,255,255,int(255*opacity))) # 合成图片 img = Image.alpha_composite( img.convert("RGBA"), watermark ).convert("RGB") results.append(torch.from_numpy(np.array(img).astype(np.float32) / 255.0)) return (torch.stack(results),)开发时踩过的坑：
- 忘记处理batch输入，导致只能处理单张图片
- 透明度参数没做范围限制，有用户输入了1.5导致报错
- 字体路径写死，在其他电脑上运行时找不到字体
4.2 模型集成节点
如果想接入自定义Stable Diffusion模型，可以这样实现：
from comfy.sd import load_checkpoint from nodes import CheckpointLoader class CustomModelLoader(CheckpointLoader): @classmethod def INPUT_TYPES(cls): return { "required": { "model_name": (["custom_model1", "custom_model2"],), } } FUNCTION = "load_model" def load_model(self, model_name): # 自定义模型路径映射 model_map = { "custom_model1": "D:/models/custom1.safetensors", "custom_model2": "D:/models/custom2.ckpt" } return load_checkpoint(model_map[model_name])5. 调试与优化技巧
5.1 常见错误排查
节点不显示：
- 检查文件是否放在custom_nodes目录
- 确认类名是否添加到NODE_CLASS_MAPPINGS
- 查看控制台是否有导入错误
参数类型错误：
- ComfyUI对类型要求严格，注意IMAGE类型是torch.Tensor
- 使用
isinstance(input, torch.Tensor)做类型检查
内存泄漏：
- 大图像处理时用
del及时释放中间变量 - 可以用
torch.cuda.empty_cache()清空显存
- 大图像处理时用
5.2 性能优化建议
批量处理： 尽量设计支持batch处理的节点，比如水印节点同时处理8张图比循环处理快3倍
GPU加速： 把numpy操作替换为torch操作：
# 慢 img_np = img.cpu().numpy() # 快 img_tensor = img.to(device="cuda")- 缓存机制： 对于模型加载等耗时操作，可以添加缓存：
_models_cache = {} def load_model(model_name): if model_name not in _models_cache: _models_cache[model_name] = load_checkpoint(model_name) return _models_cache[model_name]6. 发布与分享你的节点
6.1 打包发布
建议的项目结构：
my_custom_nodes/ ├── __init__.py ├── watermark.py ├── model_loader.py └── README.md在__init__.py中集中注册所有节点：
from .watermark import WatermarkNode from .model_loader import CustomModelLoader NODE_CLASS_MAPPINGS = { "WatermarkNode": WatermarkNode, "CustomModelLoader": CustomModelLoader }6.2 通过ComfyUI-Manager分发
- 在GitHub创建仓库
- 在
manifest.json中声明依赖和兼容性：
{ "name": "My Custom Nodes", "version": "1.0.0", "comfyui": ">=0.3.58", "dependencies": ["Pillow>=9.0.0"] }- 用户可以通过ComfyUI-Manager直接安装：
https://github.com/yourname/yournodes.git我去年发布过一个图片增强节点包，从开发到上架花了2周时间，现在已经有500+用户在使用。关键是要写好文档，特别是输入输出示例：
## 水印节点使用说明 输入参数： - images: 要加水印的图片批次 (BATCHxHxWxC) - text: 水印文字 - opacity: 透明度 (0-1) 输出： - 带水印的图片批次 示例工作流： ```json { "nodes": [ { "type": "WatermarkNode", "inputs": { "images": ["5", 0], "text": "Confidential", "opacity": 0.7 } } ] }开发自定义节点最爽的时刻，就是看到自己写的代码被集成到别人的工作流中，解决实际问题。从最简单的Hello World开始，逐步挑战更复杂的功能，你会发现ComfyUI的扩展性超乎想象。最近我在开发一个视频转GIF的节点，遇到时间轴同步的问题，正在研究用FFmpeg集成方案。