Z-Image ComfyUI 自定义节点开发指南：从零开始构建专属工作流

概述

Z-Image 的 ComfyUI 生态在 2026 年迎来了爆发式增长。随着 Z-Image Turbo、Base、Omni-Base 等多模型版本的发布，社区围绕 ComfyUI 开发了大量自定义节点和扩展工具。其中，ComfyUI-ZImagePowerNodes 作为最核心的扩展包，提供了超过 140 种风格预设、多轮对话生成、Think Block 推理机制等高级功能。

本文将带你从零开始，掌握 Z-Image ComfyUI 自定义节点的开发全流程，包括环境搭建、核心节点架构解析、实际开发案例，以及如何发布你的自定义节点到社区。

为什么需要自定义节点？

ComfyUI 的节点化工作流设计让 AI 图像生成变得高度模块化和可复用。但标准节点只能覆盖通用场景，Z-Image 的特殊架构（S3-DiT、Qwen3-4B 文本编码器、多轮对话支持）需要专门的节点来充分发挥潜力。

自定义节点的核心价值：

• 封装复杂工作流：将多个标准节点的组合打包为一个节点，简化画布
• 深度集成 Z-Image 特性：利用 Think Block、多轮对话、140+ 模板系统等专属能力
• 复用与共享：创建一次，团队或社区可随处使用
• 性能优化：减少不必要的节点间数据传输，提升生成效率

环境搭建

前置条件

开始开发前，确保你已准备好以下环境：

• Python 3.10+：ComfyUI 的核心运行环境
• ComfyUI 最新版：推荐使用 git 版本，方便调试
• Z-Image 模型文件：从 HuggingFace Comfy-Org 仓库下载三个核心文件
• Node.js 18+：如果需要在节点中添加前端 UI 组件

ComfyUI 开发环境配置

# 克隆 ComfyUI 仓库
git clone https://github.com/comfyanonymous/ComfyUI.git
cd ComfyUI

# 安装依赖
pip install -r requirements.txt

# 确认 Z-Image 模型文件就位
ls -la models/diffusion_models/z_image_turbo_*.safetensors
ls -la models/text_encoders/qwen_3_4b.safetensors
ls -la models/vae/ae.safetensors

创建自定义节点项目

# 在 custom_nodes 目录下创建你的节点包
mkdir -p custom_nodes/comfyui-z-image-custom
cd custom_nodes/comfyui-z-image-custom

# 创建基本文件结构
touch __init__.py
touch nodes.py
mkdir -p web/js

Z-Image 自定义节点核心架构

节点基础结构

每个 ComfyUI 自定义节点本质上是一个 Python 类，需要定义以下核心组件：

class ZImageCustomNode:
    # 节点在菜单中的分类路径
    CATEGORY = "Z-Image/Custom"
    
    # 输入参数定义
    @classmethod
    def INPUT_TYPES(cls):
        return {
            "required": {
                "clip": ("CLIP",),
                "user_prompt": ("STRING", {
                    "multiline": True,
                    "default": "A beautiful scene"
                }),
            },
            "optional": {
                "template_preset": (["photorealistic", "anime_ghibli", 
                                   "neon_cyberpunk", "custom"],),
            }
        }
    
    # 输出类型定义
    RETURN_TYPES = ("CONDITIONING", "STRING")
    RETURN_NAMES = ("conditioning", "formatted_prompt")
    
    # 核心处理函数
    FUNCTION = "process"
    
    def process(self, clip, user_prompt, template_preset="photorealistic"):
        # 处理逻辑
        formatted = self.format_prompt(user_prompt, template_preset)
        conditioning = clip.encode(formatted)
        return (conditioning, formatted)

Z-Image 专属特性支持

1. Think Block 机制

Z-Image 的 Qwen3-4B 编码器支持推理链（Think Block），可以让模型在生成前先"思考"：

def build_think_block_prompt(self, user_prompt, thinking_content, 
                              assistant_content):
    """构建带 Think Block 的对话格式"""
    prompt = f"""<|im_start|>system
You are a master image generator specializing in {self.style}.
<|im_end|>
<|im_start|>user
{user_prompt}<|im_end|>
<|im_start|>assistant
<think>
{thinking_content}
</think>
{assistant_content}<|im_end|>"""
    return prompt

2. 多轮对话支持

通过 ZImageTurnBuilder 的模式，节点可以维护会话上下文：

class ZImageTurnNode:
    @classmethod
    def INPUT_TYPES(cls):
        return {
            "required": {
                "previous": ("CONVERSATION",),
                "user_prompt": ("STRING", {"multiline": True}),
                "clip": ("CLIP",),
                "is_final": ("BOOLEAN", {"default": True}),
            }
        }
    
    def process(self, previous, user_prompt, clip, is_final):
        # 追加新的对话回合
        conversation = previous + [{"role": "user", "content": user_prompt}]
        if is_final:
            return self.encode_final_turn(conversation, clip)
        return (conversation,)

3. 模板系统扩展

Z-Image PowerNodes 支持通过 YAML 文件定义自定义模板：

# custom_nodes/comfyui-z-image/nodes/templates/z_image/my_style.yaml
name: cinematic_desert
system_prompt: |
  You are a cinematic photographer specializing in desert landscapes.
  Focus on golden hour lighting, dramatic shadows on sand dunes,
  and warm earth tones with deep blue skies.
add_think_block: true
thinking_content: |
  Consider the interplay of light and shadow across the desert terrain.
  Emphasize the texture of sand and the vastness of the landscape.

实战开发案例

案例 1：智能风格迁移节点

创建一个能自动从参考图提取风格并应用的节点：

import torch
from PIL import Image
import numpy as np

class ZImageStyleTransferNode:
    CATEGORY = "Z-Image/Style"
    
    @classmethod
    def INPUT_TYPES(cls):
        return {
            "required": {
                "image": ("IMAGE",),
                "clip": ("CLIP",),
                "user_prompt": ("STRING", {"multiline": True}),
                "style_strength": ("FLOAT", {
                    "default": 0.7, 
                    "min": 0.0, 
                    "max": 1.0, 
                    "step": 0.05
                }),
            }
        }
    
    RETURN_TYPES = ("CONDITIONING",)
    FUNCTION = "transfer_style"
    
    def transfer_style(self, image, clip, user_prompt, style_strength):
        # 提取参考图特征
        image_tensor = image.squeeze(0)  # [H, W, C]
        
        # 构建融合提示词
        enhanced_prompt = (
            f"{user_prompt} "
            f"[style_reference: {style_strength}]"
        )
        
        conditioning = clip.encode(enhanced_prompt)
        return (conditioning,)

案例 2：批量提示词增强节点

自动优化用户输入的自然语言提示词：

class ZImagePromptOptimizerNode:
    CATEGORY = "Z-Image/Prompt"
    
    @classmethod
    def INPUT_TYPES(cls):
        return {
            "required": {
                "prompt": ("STRING", {"multiline": True}),
                "scene_type": (["portrait", "landscape", "product", 
                               "architecture", "food"],),
                "detail_level": (["basic", "standard", "detailed", 
                                 "ultra"],),
            }
        }
    
    RETURN_TYPES = ("STRING", "STRING")
    RETURN_NAMES = ("enhanced_prompt", "formatted_output")
    FUNCTION = "optimize"
    
    def optimize(self, prompt, scene_type, detail_level):
        templates = {
            "portrait": {
                "basic": "{subject}. Portrait photo.",
                "standard": "{subject}. Shot on 85mm f/1.4, shallow DoF.",
                "detailed": "{subject}. Natural lighting, 85mm f/1.4, "
                           "shallow depth of field, Kodak Portra 400 "
                           "film emulation, soft warm tones.",
                "ultra": "{subject}. Shot on Hasselblad X1D with "
                        "80mm f/2.8, shallow depth of field, "
                        "volumetric lighting, rim light, "
                        "Kodak Portra 400 emulation, 8K detail, "
                        "natural skin texture, award-winning "
                        "editorial photography."
            },
            "landscape": {
                "basic": "{subject}. Landscape photo.",
                "standard": "{subject}. Golden hour, wide angle.",
                "detailed": "{subject}. Shot during golden hour with "
                           "warm side lighting, 24mm wide-angle lens, "
                           "deep depth of field, Fujifilm Velvia "
                           "film emulation.",
                "ultra": "{subject}. Golden hour with warm volumetric "
                        "lighting, 16mm ultra-wide lens at f/11, "
                        "deep depth of field, Fujifilm Velvia 50 "
                        "emulation, 8K resolution, dramatic clouds."
            }
        }
        
        template = templates.get(scene_type, {}).get(
            detail_level, "{subject}. Photo."
        )
        enhanced = template.format(subject=prompt)
        
        return (enhanced, f"## Enhanced Prompt\n\n{enhanced}")

调试与测试

节点调试技巧

1. 使用 Preview Text 节点：连接节点的文本输出到 Preview Text，查看格式化后的提示词
2. 检查控制台输出：ComfyUI 的控制台会打印节点的标准输出
3. 断点调试：在节点代码中添加 import pdb; pdb.set_trace() 后重启 ComfyUI

# 推荐的调试输出方式
import logging
logger = logging.getLogger("Z-Image Custom")

class MyNode:
    def process(self, ...):
        logger.info(f"Input prompt: {prompt}")
        logger.info(f"Formatted: {formatted}")
        # 使用 print 输出到控制台
        print(f"[ZImageDebug] Conditioning shape: {cond.shape}")

常见问题

问题	原因	解决方案
输出空白	CLIP 类型错误	使用 Lumina 2 CLIPLoader
图像质量差	CFG 值过高	保持 CFG 1.0-2.0
节点找不到	文件结构错误	确认 __init__.py 正确注册节点
模板加载失败	YAML 格式错误	使用 JSON 验证器检查格式
多轮对话中断	上下文未传递	确保 Conversation 类型正确传递

发布到社区

准备工作

1. 代码完善：添加类型注解、错误处理、文档字符串
2. README 编写：包含安装步骤、节点说明、示例工作流
3. 许可证选择：推荐 Apache 2.0 以兼容 Z-Image

发布步骤

# 1. 初始化 Git 仓库
cd custom_nodes/comfyui-z-image-custom
git init
git add .
git commit -m "Initial release: Z-Image Custom Nodes"

# 2. 创建 GitHub 仓库
gh repo create comfyui-z-image-custom --public --source=.

# 3. 提交到 ComfyUI Manager
# 在 ComfyUI-Manager 仓库提交 PR，添加你的节点

推荐的项目结构

comfyui-z-image-custom/
├── __init__.py          # 节点注册 & WEB_DIRECTORY
├── nodes.py             # 节点实现
├── templates/
│   └── z_image/
│       └── my_style.yaml
├── web/
│   └── js/
│       └── my_node.js   # 前端 UI 组件
├── requirements.txt     # Python 依赖
├── README.md            # 文档
└── LICENSE              # 许可证

进阶技巧

1. 利用 Z-Image 的 JSON 结构化提示

Z-Image 支持 JSON 和 YAML 格式的结构化提示，这在自定义节点中特别有用：

def build_structured_prompt(self, config):
    """从结构化配置生成提示词"""
    prompt_config = {
        "subject": config["subject"],
        "scene": config["scene"],
        "camera": {
            "lens": config.get("lens", "85mm"),
            "aperture": config.get("aperture", "f/1.4"),
        },
        "lighting": {
            "type": config.get("lighting", "golden hour"),
            "direction": config.get("direction", "side"),
        },
        "style": config.get("style", "photorealistic"),
    }
    return json.dumps(prompt_config, ensure_ascii=False)

2. 条件分支逻辑

在节点中实现条件判断，根据输入自动选择不同的处理路径：

def process(self, input_type, prompt, image=None):
    if input_type == "text_only":
        return self.text_to_image(prompt)
    elif input_type == "image_reference":
        return self.image_to_image(prompt, image)
    elif input_type == "style_transfer":
        return self.transfer_style(prompt, image)
    else:
        raise ValueError(f"Unknown input type: {input_type}")

总结

Z-Image ComfyUI 自定义节点开发是一个充满创造力的领域。通过掌握 Python 节点定义、Think Block 机制、多轮对话支持和模板系统，你可以构建出强大且易用的定制化工作流。

从简单的提示词格式化节点，到复杂的多轮对话角色生成系统，自定义节点是释放 Z-Image 全部潜力的关键。随着 ComfyUI 生态的持续发展，自定义节点开发也将成为 Z-Image 工作流设计中不可或缺的技能。

下一步推荐深入阅读 ComfyUI 官方自定义节点文档 和 ZImagePowerNodes 的源码，理解更多高级模式。