发现与导入
先确认节点目录真实位于当前实例使用的 ComfyUI 根目录，再从启动日志中确认模块是否被发现、导入或跳过。
自我图书馆SELF LIBRARY持续整理中SHELF 04 / CUSTOM NODES · EXTENSIONS
自定义节点与依赖
扩展能力，也扩展供应链。
自定义节点可以把新的模型、预处理器、文件格式或自动化逻辑接入 ComfyUI，但它们同时引入 Python 依赖、前端扩展和版本耦合。安装前先确认来源与兼容范围，开发时先把输入、输出和资源生命周期说清楚。
custom_nodes 扩展入口TYPE 连接契约VENV 依赖边界
01 / INSTALL IS A TRUST DECISION
节点安装不是“补一个按钮”，
而是在执行第三方代码。
ComfyUI 官方文档将自定义节点视为扩展机制：节点包通常位于 ComfyUI/custom_nodes，可能同时包含 Python 依赖和前端资源。官方推荐通过 ComfyUI Manager 安装已登记的节点，也允许按特定版本从 Git 仓库安装；无论哪条路径，都应先判断仓库维护者、许可证、依赖清单与目标 ComfyUI 版本是否可信和匹配。
安全边界：只安装能审查或能信任的节点。
节点包可在本地 Python 环境执行代码，也可能带来 JavaScript 前端扩展。不要为导入一张工作流而无差别安装它提示的全部依赖；先找官方仓库、发行版本、安装说明和已知兼容范围，再在隔离环境中验证。模型权重与自定义节点同样需要确认来源与许可证。
02 / LOADING LIFECYCLE
看懂启动日志，
比重装更有效。
启动时 ComfyUI 会扫描 custom_nodes 下的扩展。官方生命周期文档说明，传统后端节点包通过 __init__.py 暴露映射，例如 NODE_CLASS_MAPPINGS；某个扩展加载失败时，ComfyUI 会继续启动，但控制台会记录失败模块与堆栈。因此“界面打开了”不代表目标节点已经正常注册。
注册与显示
后端映射决定节点类如何注册；显示名称影响画布搜索与菜单。仅有前端资源并不会自动生成可执行后端节点。
版本 API
官方仓库中同时可见传统映射方式与较新的 V3 扩展示例。开发或修复时应完整遵循当前目标版本的一个官方模板，不要把不同代接口的片段拼接在一起。
03 / NODE CONTRACT
好节点先定义边界，
再实现内部算法。
对用户而言，节点是一个输入输出契约；对 ComfyUI 而言，类型信息帮助前端阻止明显错误的连接。一个节点应明确哪些输入必填、哪些可选、输出是什么、何时执行以及错误如何暴露。这样工作流才不必靠“试着接一下”来理解。
INPUT CONTRACT
required / optional · type · default · validation为模型、图像、潜变量或标量设置准确的数据类型与参数范围。前端类型检查能早发现连接错误，但业务语义和文件存在性仍应在节点中验证。
OUTPUT CONTRACT
return types · names · shape / container assumptions输出必须与下游节点期待的数据形态一致。IMAGE 的批量维度与 LATENT 的容器结构不同；若节点改变尺寸、批量或数据空间，应显式说明。
避免把“能跑一次”误认为接口正确。
自定义节点应在空输入、缺少模型、不同批量、不同尺寸和异常依赖等情况下给出可定位的失败信息。开发者还应说明它是否依赖特定模型族、是否需要 GPU、是否会下载额外文件，以及这些文件应放在哪里。
04 / PERFORMANCE & DEBUGGING
不必计算的输入，
就不应占用资源。
默认情况下，必填和可选输入会在节点执行前求值。官方 Lazy Evaluation（惰性求值）机制允许节点把某些输入标为惰性，仅在当前分支真正需要时请求它们；这能避免不必要的计算和显存占用，但节点也必须在 check_lazy_status 中清楚声明还需要哪些输入，不能把惰性设计成隐藏副作用。
先读完整错误
从启动日志或节点报错确认是导入失败、依赖缺失、模型路径、数据类型还是运行时显存问题；不要只根据画布上红框猜测。
在同一环境装依赖
节点依赖必须安装进实际运行 ComfyUI 的 Python 环境。系统 Python、另一个虚拟环境或桌面应用的内置环境并不自动共享包。
为节点留最小测试图
用一个只包含节点必要输入与可观察输出的工作流回归测试，分别验证节点本身、与上游模型的组合以及更新后行为。
READING LIST / ORIGINAL SOURCES
ComfyUI Install Custom Nodes↗ComfyUI Custom Node Lifecycle↗ComfyUI Custom Node Datatypes↗ComfyUI Lazy Evaluation↗ComfyUI 官方自定义节点示例↗
ComfyUI 的节点、工作流格式和模型支持会持续演进。本文只归纳对应资料可确认的机制；导入工作流前仍应核对 ComfyUI、节点包、模型权重与许可证的实际版本。