Back to Details

comfyui-nodes-dev

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ComfyUI V3 Custom Nodes (Server-Side)

ComfyUI V3服务端自定义节点

ComfyUI baseline: v0.12.0 (Comfy API v0_0_2). Update this line when revising the skill.
ComfyUI基准版本：v0.12.0（Comfy API v0_0_2）。修订本技能时请更新此内容。

Scope

适用范围

  • Focus on server-side V3 nodes (Python).
  • Exclude client-server extension patterns and frontend-only extensions.
  • 聚焦于服务端V3节点（Python实现）。
  • 排除客户端-服务端扩展模式及纯前端扩展。

Quick Workflow

快速工作流程

  1. Choose API adapter: 
    comfy_api.v0_0_2
    for stability or 
    comfy_api.latest
    for newest features.
  2. (Optional) Scaffold a nodepack using 
    comfy node scaffold
    .
  3. Implement a V3 node with 
    io.ComfyNode.define_schema()
    and 
    execute()
    .
  4. Return 
    io.NodeOutput
    (or tuple/dict) from 
    execute()
    .
  5. Register nodes via 
    ComfyExtension.get_node_list()
    and 
    comfy_entrypoint()
    .
  6. Restart ComfyUI and validate in UI/API.
  1. 选择API适配器：使用
    comfy_api.v0_0_2
    以保证稳定性，或使用
    comfy_api.latest
    获取最新功能。 2.（可选）使用
    comfy node scaffold
    快速搭建节点包框架。
  2. 利用
    io.ComfyNode.define_schema()
    和
    execute()
    实现V3节点。
  3. 从
    execute()
    返回
    io.NodeOutput
    （或元组/字典）。
  4. 通过
    ComfyExtension.get_node_list()
    和
    comfy_entrypoint()
    注册节点。
  5. 重启ComfyUI并在UI/API中验证节点功能。

Do / Don’t

注意事项

  • Do use classmethods 
    define_schema()
    and 
    execute()
    .
  • Do return 
    io.NodeOutput
    (or tuple/dict) from 
    execute()
    .
  • Do use 
    ui.Preview*
    helpers for UI previews.
  • Don’t store mutable instance state in nodes.
  • Don’t use client-server extension patterns (out of scope for this skill).
  • 请使用类方法
    define_schema()
    和
    execute()
    。
  • 请从
    execute()
    返回
    io.NodeOutput
    （或元组/字典）。
  • 请使用
    ui.Preview*
    助手类实现UI预览功能。
  • 不要在节点中存储可变实例状态。
  • 不要使用客户端-服务端扩展模式（超出本技能的适用范围）。

Reference Map

参考资源

Use these references as needed (progressive disclosure):
  • references/v3-core.md
    : API versions, ComfyExtension, progress reporting.
  • references/io-types.md
    : IO types, widget inputs, custom types.
  • references/schema-nodeoutput.md
    : Schema fields, flags, hidden inputs, NodeOutput patterns.
  • references/ui-helpers.md
    : Preview and save helpers for UI outputs.
  • references/scaffold.md
    : Scaffold workflow and V3 defaults.
  • references/lazy-evaluation.md
    : Lazy inputs, check_lazy_status, execution blocking.
  • references/validation-and-caching.md
    : validate_inputs and fingerprint_inputs patterns.
  • references/folder-paths-and-files.md
    : folder_paths helpers and save/load patterns.
  • references/image-mask-performance.md
    : Tensor shapes, resizing, batching, device tips.
  • Official docs: Comfy-Org/docs custom-nodes
按需使用以下参考资料（逐步披露详情）：
  • references/v3-core.md
    ：API版本、ComfyExtension、进度报告相关内容。
  • references/io-types.md
    ：IO类型、组件输入、自定义类型相关内容。
  • references/schema-nodeoutput.md
    ：Schema字段、标记、隐藏输入、NodeOutput模式相关内容。
  • references/ui-helpers.md
    ：用于UI输出的预览和保存助手类相关内容。
  • references/scaffold.md
    ：框架搭建流程及V3默认配置相关内容。
  • references/lazy-evaluation.md
    ：延迟输入、check_lazy_status、执行阻塞相关内容。
  • references/validation-and-caching.md
    ：validate_inputs和fingerprint_inputs模式相关内容。
  • references/folder-paths-and-files.md
    ：folder_paths助手类及保存/加载模式相关内容。
  • references/image-mask-performance.md
    ：张量形状、缩放、批处理、设备优化技巧相关内容。
  • 官方文档：Comfy-Org/docs custom-nodes

Template

模板文件

  • assets/v3_extension_template.py
    : Minimal V3 node + extension + entrypoint.
  • assets/v3_extension_template.py
    ：最简V3节点+扩展+入口点模板。