读 ComfyUI 源码:节点图怎样真正跑起来

这一篇读的是 Comfy-Org/ComfyUI。很多人第一次接触它，会先把注意力放在画布和节点拖拽上；但源码里更值得看的，不是“一个 Stable Diffusion 图形界面”，而是一套把 AI 生成流程拆成可发现、可校验、可排队、可缓存、可扩展执行图的运行时。

本文源码基线：本地目录 sources/comfyui；分支 master；提交 f7297bc5a9a5c9603a2926791c090bba4962d1cb；提交时间 2026-05-30T15:20:33-04:00；提交主题 Revert deprecation of non-dynamic smart memory (CORE-152 (revert)) (#14183)。源码侧还确认了 pyproject.toml 要求 Python >=3.10，许可证以仓库根目录 LICENSE 的 GPL-3.0 为准。

本文由 AI 辅助整理和改写，可能存在遗漏、理解偏差或版本差异。关键实现请以本文固定的提交、对应源码文件和官方文档为准，自行复核后再用于工程判断。

先抓住主线：后端执行图，不是画布文档

读 ComfyUI 最容易走偏的地方，是一头扎进 comfy/ 下面的采样器、模型和 tensor 细节。那些当然重要，但它们更像模型运行时的深水区，不是理解 ComfyUI 产品骨架的第一入口。

更有效的顺序是：

1. 1. 从 server.py 看 /prompt、/object_info、/queue、/history 和 /ws；
2. 2. 到 execution.py 看 PromptQueue、PromptExecutor、validate_prompt() 和缓存；
3. 3. 再读 nodes.py 的节点注册协议；
4. 4. 最后补 comfy_execution/graph.py、comfy_execution/caching.py 和 folder_paths.py。

这条线会把 ComfyUI 的核心抽象串起来：Python class 定义节点，/object_info 暴露节点 schema，/prompt 接收后端执行图，PromptQueue 排队，PromptExecutor 通过 ExecutionList 拓扑执行，缓存系统决定哪些节点需要重跑，folder_paths.py 管模型目录和 custom node 路径。

这里要特别区分两个概念：前端 workflow 和后端 prompt。workflow 里有坐标、分组、视图状态；后端 prompt 只关心可执行图，每个 node id 下面有 class_type 和 inputs，连接输入用 [source_node_id, output_index] 表示。把这两个概念混起来，就很容易误以为画布信息也参与后端执行。

启动链路：服务只是入口，worker 才是真正干活的人

main.py 的启动顺序很能说明 ComfyUI 的性格。

它先解析参数和日志，再设置 GPU、ROCm、deterministic 等运行环境；随后 apply_custom_paths() 处理 extra_model_paths.yaml、输入输出目录、用户目录和模型搜索路径。更早之前，execute_prestartup_script() 还会扫描 custom_nodes 下每个模块的 prestartup_script.py，给 custom node 一个正式加载前的启动钩子。

真正开始服务时，start_comfyui() 创建 PromptServer，调用 nodes.init_extra_nodes() 加载内置和外部节点，初始化数据库、routes 和 progress hook，然后启动 worker 线程。

这意味着 HTTP server 只是控制入口。耗时的生成任务不会直接在 route 里跑，而是进入 PromptQueue，由 prompt_worker() 循环取任务，交给 PromptExecutor 执行，完成后写 history、发 websocket 状态，并按 flag 做 unload 或 free memory。

所以，ComfyUI 的后端不是“一个带 API 的页面服务”，而是一个长期运行的执行器。HTTP 负责提交、查询和传文件；worker 负责真正执行图。

节点注册：一份 Python class 同时服务前端和后端

nodes.py 里可以直接看到节点协议。以内置的 CLIPTextEncode 为例，节点 class 会定义 INPUT_TYPES()、RETURN_TYPES、FUNCTION、CATEGORY、DESCRIPTION、SEARCH_ALIASES 等字段，实际执行函数由 FUNCTION 指向的方法承担。

主表 NODE_CLASS_MAPPINGS 把 "KSampler"、"CheckpointLoaderSimple"、"CLIPTextEncode"、"VAEDecode"、"SaveImage" 这类字符串映射到 Python class；NODE_DISPLAY_NAME_MAPPINGS 再给前端显示名。

custom node 的加载也在这条线上：load_custom_node() 可以加载单个 .py 文件或目录里的 __init__.py。传统 V1 模块暴露 NODE_CLASS_MAPPINGS 和可选的显示名映射；V3 模块可以通过 comfy_entrypoint 返回 ComfyExtension，再按 schema 注册节点。模块如果声明 WEB_DIRECTORY，前端扩展目录也会被记录到 EXTENSION_WEB_DIRS。

这套设计的价值在于，一份 node class 同时服务三件事：

• • 前端通过 /object_info 生成节点面板、输入控件和输出 socket；
• • 后端校验 prompt 时，用 INPUT_TYPES、RETURN_TYPES 检查连接和值；
• • 执行阶段通过 FUNCTION 找到真正的方法，把上游输出作为参数传进去。

也就是说，ComfyUI 的节点不是前端 palette 里的静态配置，而是前后端共同遵守的运行时协议。

/prompt 到队列：提交、校验、入堆、执行

server.py 的 /prompt 是后端执行图进入系统的入口。route 会读取 JSON，处理 number 和 front，拿到 prompt、prompt_id、partial_execution_targets，再让 NodeReplaceManager 做废弃或迁移节点的替换，最后调用 execution.validate_prompt()。

校验通过后，它把 (number, prompt_id, prompt, extra_data, outputs_to_execute, sensitive) 放进 PromptQueue。PromptQueue 不是普通列表，而是用 heapq 管优先级，用 Condition 协调 worker 等待，并维护 currently_running、history 和控制 flag。

校验本身更像一个小型类型系统。validate_prompt() 先确认每个节点有 class_type，而且类型存在于 NODE_CLASS_MAPPINGS；再只把 OUTPUT_NODE = True 的节点加入执行目标。validate_inputs() 会递归检查依赖：有没有 cycle，required input 是否缺失，连接输入是不是 [node_id, slot_index]，上游 RETURN_TYPES 和当前 input type 是否匹配，常量输入能否转换，以及 min/max、combo option 和节点自定义校验是否通过。

这解释了为什么 ComfyUI 的 prompt JSON 有很强的工具化潜力。一个 Prompt Linter 不需要先理解完整前端画布，只要沿着后端校验规则，就能指出 missing node、bad linked input、return type mismatch、value out of range、没有输出节点等问题。

执行不是递归 DFS，而是可 staging 的拓扑列表

PromptExecutor.execute() 会进入 execute_async()。它绑定 client id，发送 execution_start，通知 cache provider，创建 DynamicPrompt、progress、IsChangedCache，再批量检查哪些节点已有 output cache。

随后关键角色变成 ExecutionList。执行器只把 outputs_to_execute 放进去，然后循环做三件事：stage ready node，执行 node，根据 SUCCESS、PENDING、FAILURE 完成或回滚 staging。

单个节点执行时，系统会从 DynamicPrompt 取 inputs 和 class_type，查 NODE_CLASS_MAPPINGS，先看 output cache；未命中时，把输入转成函数参数，从 object cache 取或实例化 node 对象，再通过 FUNCTION 反射调用。节点还可以使用 lazy input，在运行时要求某些输入从弱依赖变成强依赖；也可以返回 subgraph，让执行器把 ephemeral node 加进 DynamicPrompt，并为子图创建 subcache。

这比“从输出节点递归向上求值”复杂得多。ComfyUI 需要处理 async pending、动态加边、动态加节点、cache link、subgraph 和 UI 友好的执行顺序。因此它用的是一个可 staging、可 pending、可扩展的拓扑执行列表。

缓存：为什么有些节点会重跑，有些不会

ComfyUI 的缓存也不是简单比较 node id。CacheSet 支持 CLASSIC、LRU、RAM_PRESSURE、NONE 等模式；output cache 的关键是 CacheKeySetInputSignature。

这个签名会把当前节点的 class、输入、可选 node id、IS_CHANGED 或 V3 的 fingerprint_inputs，以及有序祖先链一起纳入 cache key。连接输入不会只记“连到了谁”，还会记录祖先 index 和 socket。IsChangedCache 调节点自定义变化检测时，只使用常量输入，不依赖 cached outputs。

所以“只重新执行变化部分”这句话在 ComfyUI 里有具体含义：它看的是节点 class、输入、祖先签名、特殊变化指纹，以及是否包含 unique id 或 NOT_IDEMPOTENT，而不只是当前节点参数有没有变。

这块也很适合做成解释工具。用户最困惑的问题往往不是“怎么生成”，而是“为什么这个节点又跑了”或“为什么它没跑”。缓存签名 viewer 可以把节点、输入、祖先链和 IS_CHANGED 结果拆开给人看。

模型目录和 custom node 是主路径，不是边角功能

folder_paths.py 一开始就建立模型目录 registry。checkpoints、loras、vae、text_encoders、diffusion_models、controlnet、upscale_models、custom_nodes 等目录都会进入 folder_names_and_paths；同时它定义 input、output、temp、user 目录，处理 legacy name 映射，并用 get_full_path()、get_filename_list() 做注册目录内查找、扩展名过滤和 mtime 缓存。

custom node 主路径也不是“额外插件装饰”。它有三层：main.py 扫 prestartup_script.py，nodes.py 扫外部 custom_nodes 并加载节点，app/custom_node_manager.py 再处理 custom node 的 locales、workflow templates 和静态模板路由。

这说明 ComfyUI 的生态扩展能力并不只是“可以多装几个节点”。custom node 可以注册 Python 节点、加载前端资源、提供工作流模板、合并翻译，还能在正式加载前执行启动脚本。源码层面看，它是运行时的一等机制。

实用判断：最值得沉淀的是运行时解释器

读完这条链路后，我对 ComfyUI 的判断是：它最有复用价值的不是“节点图 UI”，而是后端运行时已经暴露出的结构化边界。

/object_info 可以做节点 schema explorer；validate_prompt() 的规则可以做 Prompt JSON linter；/queue、/history 和 WebSocket events 可以做执行回放器；CacheKeySetInputSignature 可以做缓存解释器；folder_paths 可以做模型目录 inspector；custom node 目录可以做节点依赖和前端资源索引。

这些方向的共同点是：它们顺着 ComfyUI 已经存在的协议走，不需要先碰模型推理成本，也不需要把前端 workflow、后端 prompt、模型目录和 custom node 混成一个大概念。

ComfyUI 的源码价值就在这里：它把看似自由的 AI 节点画布，落到了节点 schema、prompt graph、队列执行、拓扑调度、缓存签名和目录协议上。对读源码的人来说，这比“它支持多少模型”更关键，因为这些机制才解释了一个节点图系统如何稳定地跑起来。