ComfyUI 节点架构大变革：v3 带来稳定性、异步支持与更多可能

ComfyUI 是一个高度可扩展的图形化 AI 工作流平台，其核心优势之一在于对自定义节点（Custom Nodes）的支持。为了让开发者更高效、稳定地构建和维护这些节点，ComfyUI官方正式推出 Nodes v3 升级计划。

这一计划旨在解决长期以来困扰节点开发者的多个痛点，包括稳定性问题、依赖冲突、动态输入/输出支持不足等，并为未来的新功能打下坚实基础。

本文将详细介绍 Nodes v3 的目标、改进方向以及当前进展，并邀请所有自定义节点开发者参与讨论和反馈。

🎯 Nodes v3 解决的核心问题

🔒 提升稳定性

目前，ComfyUI 的每次更新都可能导致部分自定义节点失效。这是因为“内部 API”与“公共接口”之间缺乏清晰界限，使得即使是高质量的扩展也容易受到影响。

为此，我们将建立一套稳定的公共 API 接口，并提供文档支持与向后兼容性保证。使用这套 API 的节点将不再受底层实现变化的影响。

📦 解决依赖冲突

每个自定义节点都有自己的依赖包，而当多个节点安装在同一环境中时，依赖冲突可能导致整个 ComfyUI 安装崩溃。

为了缓解这一问题，我们正在探索隔离运行机制——即为每个基于公共 API 的节点分配独立的 Python 进程。这样即使不同节点使用了相同库的不同版本，也不会互相干扰。

⚙️ 支持动态输入/输出

虽然现有系统允许添加动态输入/输出字段，但某些功能无法很好地与其配合工作。

v3 将提供更加面向对象、结构清晰的节点编写方式，让动态行为的实现更自然、更可靠。

💡 改进自定义控件

我们希望让开发者更容易地在前端添加自定义控件，并在执行过程中动态更新它们的状态。尽管这在当前版本中是可能的，但实现过程复杂且易受更新影响。

v3 将简化这一流程，使控件定义更直观，状态同步更稳定。

🗃️ 简化模型管理

随着新模型不断出现，用户常常面临一个问题：“我有哪些模型？还需要下载哪些？应该放在哪个目录？”特别是在模型体积越来越大的情况下，这个问题尤为突出。

我们将在未来加入更好的模型识别、自动下载和路径管理机制。

🚀 支持未来迭代

虽然目前的重点是节点本身，但我们也在为未来的高级功能做准备：

• 多机分布式工作流执行；
• 单机多节点并行处理；
• 更灵活的节点调度与资源管理。

🧩 Nodes v3 的设计思路

✨ 公共 API 体系

我们将为自定义节点创建一个明确划分的公共 API 层，以确保：

• 节点不会因 ComfyUI 内部重构而失效；
• 开发者能获得清晰的接口文档和类型提示；
• 向后兼容性得到保障。

对于尚未完全迁移到公共 API 的节点，我们将继续支持旧模式，但鼓励开发者逐步转向新标准。

🧱 模块化节点结构

v3 引入了一种新的节点定义方式：

• 输入、输出和参数以对象形式声明；
• 所有配置信息统一通过 DEFINE_SCHEMA 方法集中管理；
• 输出项需与输入一一对应，以支持动态行为；
• 类方法采用无状态设计（类方法而非实例方法），提升跨环境执行能力。

这种方式不仅提升了代码的可读性，也为后续扩展提供了良好的结构基础。

🔄 版本化的 API 支持

为了兼顾灵活性与稳定性，我们将 API 分为两个阶段：

我们还将提供适配器机制，帮助老节点平滑过渡到新版本，同时指导开发者如何利用新版 API 实现更多功能。

📏 异步调用支持

v3 中的 API 将默认使用异步函数（async def / await），这是实现并行执行和进程外执行的关键。

不过，如果你不想深入异步编程，只需遵循两条简单规则即可：

1. 使用 async def 替代 def；
2. 在调用异步函数前加上 await。

你仍然可以调用非异步库，无需担心兼容性问题。（来源）