技术手册 /
ComfyUI 本地部署 /
排错与维护（进阶）
排错与维护（进阶）
12-ComfyUI 本地部署 · 2026-10-12 · 2.7 KB
快速开始跑通之后会遇到的几件事：启动失败 / 连不上 / 显存不够 / 权重维护 / 更新与卸载 / 共用权重。
本专题手工维护；⚠ 具体界面文案以你应用内的设置为准 ✓
一、启动阶段
| 现象 | 排查顺序 |
|---|---|
双击 run_nvidia_gpu.bat 秒退 | ① 路径是否含中文/空格（换纯英文短路径）② 杀软是否拦截（加信任）③ 系统是否缺 VC++ 运行库 / 显卡驱动 |
| 控制台卡在加载节点很久 | 首次启动要加载 80+ 节点：等 1~3 分钟；⛔ 别重复双击（会起多个实例抢端口） |
| 提示端口被占用 | 已有别的 ComfyUI/程序占了 8188 ⇒ 换端口：改包内启动脚本的 --port ＋ 改应用设置里的端口（两边一致）✓ |
| 黑窗一闪就没、看不到报错 | 用启动器（UnlimitCanvasLauncher.exe）启动，它会保留输出；或看包内 logs\ 目录 ✓ |
⚠ 应用通过启动脚本拉起 ComfyUI 时，错误输出会写到根目录的 unlimitcanvas-comfyui.err.log ⇒ 应用里点启动却起不来，先看这个文件 ✓
二、连接阶段（应用 ↔ ComfyUI）
判定链：应用认为"本地引擎可用"的条件，就是能访问 ComfyUI 的 /system_stats ✓
| 现象 | 原因 | 处置 |
|---|---|---|
| 设置里「测试连接」不通 | 本体没起 / 端口不一致 / 防火墙 | 浏览器先试 http://127.0.0.1:<端口> ⇒ 通不了就先修本体 |
| 浏览器能开，应用不通 | 应用里端口填错（改了包没改应用，或反之） | 两边端口改成一致，应用侧改完点测试 |
| 应用能连，但自检有红项 | 节点缺失 / 插件依赖没装齐 | 按自检提示处理；⚠ 本包的节点是预装好的，红项通常指向你自己装/删过的节点 |
| 换了端口后就再也连不上 | 应用在启动 ComfyUI 时会带 --port <应用里的端口> | 让应用来启动（它会用设置里的端口）；或两边手工对齐 ✓ |
⚠ 如果连不上的是"另一台机器"（局域网里的第二台）：判据不一样 —— 要求那台开着且这台能访问到它，地址填 http://<那台IP>:8188（免 token）、inputDirectory 必填 ⇒ 见《局域网算力集群》✓
三、显存与档位（跑不动 / 爆显存）
- 应用内置模型档位机制：同一模板会按你的显存/架构挑合适的精度档（如 fp8 / int4 / 量化版）
- 跑不动时依次试：
- 降到更低档（在节点参数里选更轻的模型/精度）
- 减分辨率 / 减帧数 / 减时长（视频类尤其有效）
- 换更轻的模板（先跑通，再上重的）
- 显存提示：本地任务在应用里是串行排队的 ⇒ 别同时点多个重模板（会排队，但不会互相抢显存 ✓）
四、权重（模型）维护
| 事 | 怎么做 |
|---|---|
| 判断有没有下完 | 目录里若还有 .part ⇒ 没下完（重新下载/续传）✓ |
| 缺哪些 | ①启动器的缺失检测 ②02-模型依赖总表.md 按模板查 ✓ |
| 完整性校验 | 包内 data\ 里有模型清单 / 状态 / 校验报告（启动器生成）⇒ 用启动器重新检测即可 ✓ |
| 想腾空间 | 只删明确不需要的权重（按 02 表对照）⇒ ⛔ 别删 ComfyUI\ 本体与 python_embeded\ ✓ |
| 权重放哪 | 见 01-模型依赖与目录规范.md（放错＝没放 ✗） |
五、更新 / 备份 / 卸载
| 动作 | 做法 |
|---|---|
| 更新程序（节点/本体升级） | ①先停掉 ComfyUI ②用新版覆盖 ComfyUI\、python_embeded\、UnlimitCanvas启动器\、tools\ ③保留你的 models\ 与 data\ ⇒ 权重与检测记录不会丢 ✓ |
| 备份 | 只需备份 ComfyUI\models\（权重最贵）＋ data\（状态）⇒ 程序部分可随时重下 ✓ |
| 卸载 | 绿色包直接删目录即可（不写注册表）⇒ 顺手把应用设置里的「启动文件/根目录」清掉 ✓ |
| 换机器 | 拷 models\ ＋ 程序目录 ⇒ 在新机器上按《快速开始》重新指一次启动脚本 ✓ |
六、与已有 ComfyUI 共用权重
- 包内
ComfyUI\extra_model_paths.yaml.example⇒ 改名为extra_model_paths.yaml并按注释填你的 models 路径，重启生效 ✓ - ⚠ 两个 ComfyUI 不要同时用同一个端口；也更不建议同时对同一
models目录做写操作（下载中尤其）✓
七、许可与合规（重要）
- 权重各有各的许可：动手商用、再分发、二次训练之前，先看该模型自身的许可条款
- 应用内对部分模型有许可警示（模板详情/使用时会提示）⇒ 请以提示与模型官方页面为准 ✓
- 本包只带节点代码、不带全部权重（节点与模型分离）⇒ 你补的每个权重，其许可由你自行确认 ✓
八、一句话排错口诀
先看本体：浏览器能不能开 http://127.0.0.1:<端口>？
再看端口：包与应用两边是不是同一个？
再看权重：文件在不在“依赖表写的那个目录”、有没有 .part？
最后看日志：包内 logs\ 与根目录 unlimitcanvas-comfyui.err.log
来源：E:/workbuddyProj/unlimitCanvas/ai_manual/comfyui_local/03-排错与维护.md