简介面向需要在 ComfyUI 中本地部署 SDXL-EcomID 节点、但受网络访问限制难以获取完整代码的用户提供一套可直接落盘的完整版本。7z 压缩包共 193 个文件约 142.66MB包含 23 个 py 源码与 23 个 pyc 缓存、10 个 json 配置或工作流文件、56 张 png 示例与预览图以及 sample、md 说明和 Git 元数据等覆盖节点运行所需的主体代码、示例素材与版本信息。已有 423 人学习适合想研究节点实现、复现示例工作流或排查依赖与加载问题的中高级用户。拿到后可按目录结构梳理模块组成对照 json 与样例图验证节点效果并借助源码定位参数逻辑和常见报错来源减少从零查找文件与反复试错的时间。1. 装 SDXL-EcomID-ComfyUI 之前先看清这套环境依赖哪些关键组件这套 SDXL-EcomID-ComfyUI 完整版本最不容易出问题的地方不在 ComfyUI 节点本身而在于它背后的三个运行时依赖PyTorch 与 CUDA 的版本匹配、用于人脸特征提取的 insightface、以及 onnxruntime-gpu 的 CUDA 大版本对应。我见过太多人把 comfy 节点 SDXL_EcomID_Comf 整个目录拷进 custom_nodes启动日志干干净净节点面板里却连一个 EcomID 的影子都没有也不报错就这么一直等也不出图。这套环境适合已经跑过 SDXL 基础出图、想做人像身份保持换装、换背景、保持脸的人如果你连 SDXL 的 checkpoint 都没加载成功过建议先把它跑通再来。下面按「装什么版本 → 怎么装 → 装坏了怎么救」的顺序走一遍。2. 环境准备Python、PyTorch、CUDA 与 ComfyUI 主体的版本对齐在 ComfyUI 上安装自定义节点最容易产生误解的一点是它由一堆独立安装的软件包组成并不是一个单一软件。节点包只是最外层底下压着 Python 解释器、PyTorch 的 CUDA 编译版本、onnxruntime 的 CUDA 编译版本、以及一堆需要本地编译的 C 扩展。这四层中只要有一层版本对不上症状往往不是报错而是「静默失败」节点不出现、加载后没反应、出图全黑。所以装之前我习惯先把各层的版本固定下来而不是先动手。2.1 Python、PyTorch、onnxruntime 的版本对照先把版本表列在下面这张表里的组合是我在多台机器上反复验证之后保留下来的默认选择组件建议版本为什么选它版本选错的典型症状操作系统Windows 10/11 64 位或 Ubuntu 22.04Windows 下便携包最省事Linux 编译依赖最省心无Python3.10 或 3.113.12 上部分依赖还没有预编译 wheelpip 找不到 wheel只能源码编译然后卡在编译报错PyTorch2.x cu121 系列与主流 onnxruntime-gpu 的 CUDA 12 构建对齐CUDA 版本不匹配torch.cuda.is_available()返回 Falseonnxruntime-gpu与 CUDA 大版本一致CUDA 12 就配 1.17人脸检测、特征提取走的是 onnx 推理检测阶段直接抛 CUDA provider 相关的异常insightface0.7.x提供人脸检测与 512 维特征装不上或装上了但 import 就崩numpy低于 2.0大批旧 wheel 是按 numpy 1.x 编译的numpy.dtype size changed或_ARRAY_API not foundVisual Studio Build Tools2019/2022勾选 C 生成工具源码编译 insightface 时必需报error: Microsoft Visual C 14.0 or greater is required这张表里最容易被忽略的是 numpy 那一行。ComfyUI 本体更新到新版本之后pip 顺手把 numpy 升级到 2.x然后所有按 numpy 1.x 编译的 C 扩展会在 import 阶段直接崩掉报错信息里还看不到 numpy 三个字。我现在的习惯是装完任何节点之后立刻执行一次版本检查把 numpy 钉死在 1.x。# 用 ComfyUI 自己的解释器查不要用系统的 python python -c import numpy, torch, onnxruntime; \ print(numpy, numpy.__version__); \ print(torch, torch.__version__, cuda, torch.version.cuda); \ print(ort, onnxruntime.__version__, onnxruntime.get_available_providers())这段输出的信息量很大torch.version.cuda是 PyTorch 编译时用的 CUDA 版本必须和显卡驱动支持的上限一致onnxruntime.get_available_providers()里如果没有CUDAExecutionProvider说明装的是 CPU 版 onnxruntime人脸检测会慢到让你以为程序卡死。最后那个列表只有CPUExecutionProvider的话直接重装 onnxruntime-gpu不用犹豫。2.2 装 ComfyUI 主体便携包与源码两条路Windows 上我一般直接用便携包解压后目录里会有一个python_embeded文件夹这就是整套环境的解释器和 site-packages 所在。注意它是embeded而不是embedded这个拼写错误是官方包自带的后面所有 pip 命令都要指向这个路径别写错了。Linux 上走源码加 venv可控性更好出问题也容易定位。# Linux / macOS 走这条路 git clone https://github.com/comfyanonymous/ComfyUI.git cd ComfyUI python3.11 -m venv venv source venv/bin/activate pip install --upgrade pip # 关键先装 torch再装 requirements顺序反了会被 requirements 里的 torch 版本覆盖 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121 pip install -r requirements.txt:: Windows 便携包不要激活任何虚拟环境直接用包内的解释器 cd /d D:\ComfyUI_windows_portable python_embeded\python.exe -m pip install --upgrade pip :: 后续所有 pip 操作都写成 python_embeded\python.exe -m pip install xxx为什么强调先装 torch因为很多节点的requirements.txt里会写torch而不带版本约束pip 判断「已满足」就直接跳过判断「不满足」就给你装个 CPU 版的默认构建结果是你明明有显卡跑图却慢十倍。先手动把带 cu121 的 torch 装进去pip 就不会再动它。这个顺序我踩过一次坑之后就再没变过。2.3 目录规划与 extra_model_paths.yaml模型文件是这套东西里最占空间的部分SDXL 基础模型单个 6.5G 左右加上身份编码、检测模型、LoRA一个干净的 ComfyUI 目录很容易膨胀到几十 G。如果有多套 ComfyUI 或者想统一管理模型用extra_model_paths.yaml把模型目录外挂进来而不是复制粘贴。配置文件放在 ComfyUI 根目录模板是extra_model_paths.yaml.example复制一份改名即可。# extra_model_paths.yaml my_sdxl: base_path: D:/ai_models/ checkpoints: sdxl/checkpoints loras: sdxl/loras clip_vision: clip_vision # 有些节点包会自己定义读取目录的类型名写了不认识会直接忽略不会报错 insightface: insightfacebase_path是后面所有相对路径的根其他每一项都是相对于它的子目录。这里有个细节checkpoints、loras、clip_vision是 ComfyUI 内置认得的类型名写错一个字母这一行就被静默忽略启动之后模型下拉框里是空的你很难第一时间想到是 yaml 拼错了。改完这个文件必须重启 ComfyUI因为它只在启动时读一次。2.4 先把 ComfyUI-Manager 装上无论后面用不用它装节点Manager 都值得先装。它能做两件很实在的事一是启动时检查所有自定义节点的依赖是否齐全二是节点加载失败时给出比原生日志具体得多的错误原因。安装方式就是从 Manager 的仓库把目录放进custom_nodes重启。cd ComfyUI/custom_nodes git clone https://github.com/ltdrdata/ComfyUI-Manager.git # 回到根目录重启启动日志里会出现 [Manager] 开头的几行装完之后重启一次日志里能看到 Manager 的版本和它扫描到的节点数量。如果这一段没有出现说明目录层级放错了——最常见的错误是把仓库里的子目录拷出来而不是整个仓库目录。判断标准很简单custom_nodes/ComfyUI-Manager/下面应该直接能看到__init__.py。3. 安装 SDXL_EcomID_Comf 节点从目录拷贝到依赖处理主体跑起来之后才轮到 comfy 节点 SDXL_EcomID_Comf 登场。这一步看着只是「把文件夹扔进去」实际上一半的翻车都发生在这里因为节点目录里那个requirements.txt会把前面辛苦对齐的版本关系全部打乱。3.1 先确认目录结构对不对不管是下载的完整版本压缩包还是 git clone放进custom_nodes之后的目录层级必须是「文件夹 → 直接就是__init__.py和节点代码」。很多人解压出来是SDXL-EcomID-ComfyUI-main再进去一层才是真正的节点目录直接把外层扔进去ComfyUI 扫不到任何东西日志里也不报错。# 检查层级这条命令能列出 __init__.py 就说明位置对了 ls ComfyUI/custom_nodes/SDXL_EcomID_Comf/__init__.py # 如果解压出来多了一层把内层挪上来不要留嵌套 mv ComfyUI/custom_nodes/SDXL-EcomID-ComfyUI-main ComfyUI/custom_nodes/_tmp mv ComfyUI/custom_nodes/_tmp/SDXL_EcomID_Comf ComfyUI/custom_nodes/ rm -rf ComfyUI/custom_nodes/_tmp目录名带不带连字符、大小写如何本身不影响加载加载靠的是目录里的__init__.py。但目录名最好保持和节点包一致以后更新、排错、按名字 grep 日志的时候不会找不到。另外custom_nodes下如果存在__pycache__残留而且它是从别的机器拷过来的也可能导致加载读到旧字节码换机器时顺手删掉。3.2 依赖安装逐行检查 requirements.txt 再动手节点自带的requirements.txt我一般不会直接pip install -r而是先打开逐行看。原因很实际里面通常混着三类东西一类是纯 Python 包opencv、timm、einops装了基本没事一类是带 CUDA 约束的包onnxruntime-gpu装了可能把已有环境降级一类是需要本地编译的包insightface这一行往往会卡住整条命令导致后面的包全都没装上。# Windows 便携包 python_embeded\python.exe -m pip install -r custom_nodes\SDXL_EcomID_Comf\requirements.txt # 更保险的做法先装纯 Python 那批编译类单独处理 python_embeded\python.exe -m pip install opencv-python timm einops facexlib filterpy第二条命令里那几个包是这类人脸身份保持节点最常见的公共依赖opencv-python处理图像读写timm提供 backbone 结构einops做张量重排facexlib做人脸对齐filterpy做时序平滑。这些包纯 Python 或带预编译 wheel装起来几秒钟的事不会污染 torch 和 onnxruntime 的版本。真正需要小心的只有两行onnxruntime-gpu和insightface。前者的版本号决定了它链接哪个 CUDA 版本如果它写的版本比你的 CUDA 新装完get_available_providers()里就会少了 CUDA provider后者的 wheel 在很多 Python 版本和平台上根本没有pip 会自动转去源码编译然后失败。3.3 insightface 装不上时的三种解法这个包是我装这套环境时遇到过问题最多的一个。它带 Cython 扩展需要本地 C 编译链Windows 上还依赖 Windows SDK。常见的三种解法按推荐顺序排列第一种直接装预编译 wheel。很多第三方会提供对应 Python 版本和平台的 whl 文件下载后本地安装不需要编译链。判断 wheel 是否匹配看文件名里的cp310、cp311对应 Python 版本和win_amd64/linux_x86_64。# 本地 wheel 安装注意路径别带中文和空格 python_embeded\python.exe -m pip install insightface-0.7.3-cp311-cp311-win_amd64.whl第二种补齐编译环境后源码安装。Windows 上装 Visual Studio Build Tools勾选「使用 C 的桌面开发」装完重开终端pip 才能读到新的环境变量。这一步没重开终端是最常见的疏忽明明装好了还是报找不到编译器。python_embeded\python.exe -m pip install insightface --no-build-isolation--no-build-isolation的作用是让编译过程使用当前环境里已有的 numpy、cython而不是临时新建一个隔离环境。因为隔离环境里装的往往是最新版 numpy编译出来的产物和主环境的 numpy 对不上装完 import 就崩。加上这个参数能避开一大类莫名其妙的二进制不兼容。第三种用 CPU 版本先把流程跑通再回头解决 GPU。pip install insightface成功后如果 onnxruntime 用的是 CPU provider人脸检测会慢但能出图能验证节点接线、参数、工作流是否正确。等整个链路确认无误再去动 onnxruntime-gpu把变量拆开出问题才知道是哪一步引入的。3.4 装完立刻做一次导入自检不要等启动 ComfyUI 才发现依赖有问题。节点目录装好之后直接用解释器 import 一次报错信息比 ComfyUI 日志清晰得多而且能定位到具体是哪个模块。python_embeded\python.exe -c import insightface, onnxruntime, cv2; print(ok) # Windows 如果报 DLL load failed多半是 onnxruntime 的 CUDA 依赖没找到 # Linux 上用 ldd 查具体缺哪个 so这一步报DLL load failed while importing onnxruntime_pybind11_state基本都是 onnxruntime-gpu 的版本和 CUDA、cuDNN 对不上卸载重装对应版本即可不用去翻节点代码。报No module named xxx说明requirements.txt里那一行没装上回头单独补。这个自检我一般会写进部署脚本几十秒的事能省掉后面半小时的瞎猜。4. 模型与参数让 EcomID 节点真正跑出第一张图节点能加载只说明代码层面通了能不能出图取决于模型文件放没放对、参数配没配对。这一层的问题更隐蔽因为什么都不报就是出图结果不对。4.1 模型清单与放置路径这套东西要用的模型不止一个按用途分三类放在不同目录节点会自动去对应位置找用途放到哪个目录说明SDXL 基础模型models/checkpoints出图主体必须是 SDXL 架构SD1.5 的模型放进来会直接报维度不符身份注入权重models/loras或节点自建目录有些包要求放节点目录下的models以节点内的路径提示为准视觉编码器models/clip_vision负责把参考图编码成特征缺了它节点会读不到参考图人脸检测与识别models/insightface/models/目录名通常是buffalo_l这样的一层注意不要多套一层同名目录最后一行的路径结构是翻车高发区。insightface 的模型加载逻辑是「根目录 模型名」拼出来的正确的结构是models/insightface/models/buffalo_l/*.onnx。很多人解压出来变成buffalo_l/buffalo_l/*.onnx程序找不到文件抛一个和路径毫无关系的异常你根本联想不到是解压多套了一层。# 用 extra_model_paths.yaml 外挂时的写法路径末尾不要带斜杠 insightface: insightface/models改完重启在节点的模型下拉框里逐个确认能看到对应文件名。下拉框是空的八成是路径问题而不是模型损坏。4.2 节点参数逐个拆参数面板里最影响结果的是这几个我按优先级说权重/强度weight控制身份特征注入的强度。太低脸不像太高会把人脸「焊」上去导致光照、肤色、脸型和原图割裂。我一般从 0.8 起按出图效果在 0.6 到 1.0 之间调。起始步数start_at从第几步开始注入身份特征。设成 0 表示全程注入通常会导致构图被参考图锁死常见做法是 0.1 到 0.2让前面几步先把构图和姿态定下来。结束步数end_at到第几步停止注入。留一点尾部步数给模型自己收细节脸部纹理更自然一般设 0.8 到 0.9。采样步数stepsSDXL 下 25 到 30 步够用低于 20 细节明显糊高于 35 收益很小纯烧时间。CFG5 到 7。SDXL 对高 CFG 比较敏感超过 8 容易出现色彩过饱和、皮肤发蜡。采样器dpmpp_2m配karras是我默认的组合兼顾速度和细节。想看更多变化可以试euler_ancestral但同一种子下结果差异会比较大不适合做对比实验。参数的调整顺序建议是先把步数和 CFG 固定只调 weight找到脸像与不像的临界点再固定 weight调 start_at 和 end_at 修细节最后才动采样器。一次只动一个变量不然出问题你根本不知道是哪个参数导致的。4.3 工作流接线与首图最小可用工作流包含四个部分加载 SDXL 模型、加载参考图并编码、EcomID 身份注入节点、KSampler 加 VAE 解码保存。接线时最容易错的是把参考图的图像输出直接连到采样器的 latent 输入上——那是完全不同的两种数据类型节点会拒绝连接或者接上之后出纯色图。# 用脚本方式批量跑图时参数大致是这么组织的字段名以节点实际定义为准 prompt { positive: a full body product shot of a model wearing a linen shirt, studio light, 1024x1024, negative: blurry, extra fingers, deformed face, watermark, text, seed: 20240513, steps: 28, cfg: 6.0, sampler: dpmpp_2m, scheduler: karras, ecomid_weight: 0.85, # 身份强度先固定这个再调别的 start_at: 0.15, # 让构图先成型 end_at: 0.85, # 尾部留给模型收细节 }第一次跑建议用 1024×1024和 SDXL 的原生训练分辨率一致出问题的概率最低。宽高比偏离太多比如 512×1024容易出现脸被拉长、肢体重复这类问题不是节点造成的是 SDXL 本身的短板别急着去改节点参数。首图跑通之后再考虑放大、加 ControlNet 控姿势一层一层加每加一层验证一次。5. 常见问题排查节点标红、依赖崩了、显存爆了怎么救装这类节点包出问题几乎是必然的区别只在于能不能快速定位。下面这几条是我实际遇到过、并且反复在别人机器上见到的按「现象 → 原因 → 解决」记下来。5.1 节点面板里搜不到 EcomID现象启动日志正常结束ComfyUI 能打开右键菜单里搜EcomID什么都没有日志里也没有任何IMPORT FAILED字样。原因三种可能。目录层级多套了一层__init__.py不在custom_nodes/节点目录/的直接子级节点目录名里带了非法字符或者空格节点包的注册名和你搜的关键词不一致实际注册的是别的名字。解决先ls custom_nodes/SDXL_EcomID_Comf/__init__.py确认层级再翻启动日志搜custom_nodes关键字ComfyUI 会把扫描到的每个目录都打出来。如果目录在列表里但节点没有就是代码层面 import 失败被吞了异常换成手动 import 一次错误就出来了。5.2 import 时报 numpy 或二进制不兼容现象启动直接抛numpy.dtype size changed, may indicate binary incompatibility或_ARRAY_API not found整个程序起不来。原因numpy 被升级到了 2.x而 opencv、insightface 这些包是按 1.x 编译的 C 扩展二进制接口对不上。解决把 numpy 降回 1.x 并锁住然后重装受影响的包让它们针对当前 numpy 重新链接。python_embeded\python.exe -m pip install numpy2 python_embeded\python.exe -m pip install --force-reinstall opencv-python # 装完立刻验证别等启动 python_embeded\python.exe -c import numpy, cv2; print(numpy.__version__, cv2.__version__)装完一定要验证因为 pip 的依赖解析可能在你装别的包时又把 numpy 顶回 2.x。我现在的做法是装完所有依赖最后统一降一次 numpy顺序放在最后。5.3 采样时显存不足或出图全黑现象点「运行」之后进度条走到采样阶段卡住日志刷out of memory或者不报错但出来的图是纯黑、纯灰、噪点。原因显存不足多数是分辨率开太大或同时加载了两套 SDXL 权重全黑图则通常和 VAE 精度有关半精度 VAE 在某些显卡上会溢出成 NaN。解决显存问题先加启动参数降占用再考虑降分辨率黑图优先换 VAE 精度。:: 显存 8G 以下加这个会牺牲一部分速度换显存 python_embeded\python.exe -s ComfyUI\main.py --windows-standalone-build --medvram :: 再到启动参数里加 --fp32-vae解决半精度 VAE 出黑图--medvram会把部分模型分块搬到内存速度慢一些但能跑起来--lowvram更激进8G 以下才建议用。这两档不要同时加会互相覆盖。黑图如果换--fp32-vae之后正常就说明是精度问题不用再折腾别的。5.4 更新之后整个环境起不来想回滚现象Manager 里点了「更新全部」重启之后一堆节点标红甚至连 ComfyUI 本体都启动失败。原因批量更新会把共享依赖一起升级torch、numpy、onnxruntime 任意一个跳版本都可能连锁崩。这类更新没有事务装一半失败就是半个残废环境。解决更新前把整个环境目录复制一份这是最土也最有效的后悔药。已经崩了的话先看日志里第一个IMPORT FAILED的包单独降级它不要一上来就重装全部。# 更新前的备份20 秒的事 cp -r ComfyUI ComfyUI_bak_$(date %m%d) # 崩了之后先降级最近升级的那个包 python_embeded\python.exe -m pip install 包名旧版本号6. 装完怎么验证三张图跑通 EcomID 的身份保持闭环装完不等于跑通我一般会用三张图做一轮验证覆盖从加载到出图的关键环节。第一张用纯文字提示词不接参考图验证 SDXL 基础模型和采样器是否正常第二张接一张清晰正脸参考图weight 设 0.85验证身份注入链路是否通第三张换一张侧脸或戴帽子的参考图验证检测模型在这种角度下是否还能提取到特征。三张都过这套环境才算能用。验证时不要只看图好不好看要看几个具体信号。启动日志里应该出现节点加载成功的行以及 insightface 加载模型的那几行采样过程中显存占用应该有明显的爬升然后回落出图之后用同一张参考图换个种子再跑一次脸应该基本一致如果每次都变说明身份特征根本没注入进去weight 调多高都没用。验证项期望结果不符合时先看哪节点出现在右键菜单能搜到并正常添加目录层级、__init__.py、启动日志模型下拉框有内容能看到 checkpoint 和 clip_vision 文件extra_model_paths.yaml、目录别名拼写参考图能编码采样日志中检测阶段有输出insightface 模型路径是否多套了一层同参考图换种子脸部特征基本一致weight、start_at、end_at显存峰值8G 卡在 1024×1024 下不爆是否误开了两套模型、是否加了--medvram验证脚本我习惯留一份在根目录就三行检查 provider、检查节点目录、检查模型文件是否存在。每次动过依赖就跑一遍比出事之后再翻日志快得多。# 放在 ComfyUI 根目录改完环境随手跑 python_embeded\python.exe -c import onnxruntime as o; print(o.get_available_providers()) dir custom_nodes\SDXL_EcomID_Comf\__init__.py dir models\insightface\models\buffalo_l\*.onnx从那以后我每次装这类带人脸特征提取的节点都会强制走一遍「先查 provider、再手动 import、最后三张图验证」的流程不管多急都不跳。血泪经验就是跳过验证省下的十分钟后面要花两小时去找一个根本不报错的静默失败。希望帮到你。本文还有配套的精品资源点击获取