企业官网建设流程全解析

简介：面向需要在 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 的版本对照

先把版本表列在下面，这张表里的组合是我在多台机器上反复验证之后保留下来的默认选择：

这张表里最容易被忽略的是 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: insightface

base_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 模型清单与放置路径

这套东西要用的模型不止一个，按用途分三类，放在不同目录，节点会自动去对应位置找：

最后一行的路径结构是翻车高发区。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。
• 采样步数（steps）：SDXL 下 25 到 30 步够用，低于 20 细节明显糊，高于 35 收益很小，纯烧时间。
• CFG：5 到 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 "numpy<2" 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 调多高都没用。

验证脚本我习惯留一份在根目录，就三行：检查 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、最后三张图验证」的流程，不管多急都不跳。血泪经验就是：跳过验证省下的十分钟，后面要花两小时去找一个根本不报错的静默失败。希望帮到你。

本文还有配套的精品资源，点击获取