ComfyUI WanVideo 视频生成避坑指南：三步先出片，五类卡点一次自查

【免费下载链接】ComfyUI-WanVideoWrapper项目地址: https://gitcode.com/GitHub_Trending/co/ComfyUI-WanVideoWrapper

ComfyUI-WanVideoWrapper 是面向 WanVideo 视频模型的 ComfyUI 节点包，覆盖模型加载、采样、LoRA 与显存管理全流程。本文先教你用官方示例工作流出第一条视频，再按依赖、文件、显存三条轴自查卡点，附参数表与错误速查表。适合首次搭建者和被配置卡住的开发者。

先出片：官方工作流三步跑通 WanVideo 视频

出片优先，排查靠后。这一章不讲环境，直接走"导入工作流 → 补齐模型 → 排队运行"的最短路径；任何一步卡住，跳到下一章对应轴去查。

第一步：把插件放进 custom_nodes

cd ComfyUI/custom_nodes git clone https://gitcode.com/GitHub_Trending/co/ComfyUI-WanVideoWrapper

预期输出：custom_nodes/下多出ComfyUI-WanVideoWrapper目录。入口init.py 的加载逻辑值得先知道：nodes、nodes_sampler、nodes_model_loading、nodes_utility、cache_methods这 5 个必需模块导入失败会直接抛异常；其余 26 个扩展模块（HuMo、FlashVSR、ATI、SkyReels 等）失败只打印WanVideoWrapper WARNING，核心流程照常。所以"部分节点缺失"几乎总是可选依赖没装，不是装坏了。

第二步：拖入示例工作流，补齐四类模型文件

仓库自带 40 多份可直接导入的 JSON，从最小的 1.3B 模型开始：

ls example_workflows | grep 1_3B

预期输出：6 个文件，如wanvideo_1_3B_VACE_examples_03.json、wanvideo_1_3B_control_lora_example_01.json。任选一个拖进 ComfyUI 画布，再把四类模型放进 readme.md 固定的目录（folder_paths机制决定下拉框只扫这些位置）：

很多人以为GGUF 量化模型需要专用加载器，实际上nodes_model_loading.py 第 53 行已把unet_gguf注册进diffusion_models的扫描列表，.gguf文件直接丢进该目录，在WanVideoModelLoader下拉框里就能选中——小显存显卡省显存不用绕路。

⚠️ 跑之前确认两件事

• 关闭其他正在运行的 ComfyUI 进程，避免占用模型文件与端口
• 启动日志若出现Found N other WanVideoWrapper directories，说明custom_nodes下有多份插件拷贝，删到只剩一份再重启，否则节点互相冲突

第三步：Queue Prompt，用 nvidia-smi 盯住首跑

确认各 loader 下拉框都选到模型后点击 Queue Prompt。判定标准：日志滚动采样进度，完成后ComfyUI/output/出现 mp4；同时开着nvidia-smi记下峰值显存，这个数字是后面一切调参的基准。如果卡在加载阶段不动，按下一章"模型文件"或"显存"轴走。

跑不通时自查：依赖、文件、显存三条轴

排查顺序是"症状 → 判定 → 修复"，不按时间线一步步重走安装流程。先按日志把症状归到一条轴上。

依赖轴：怎么装才生效

症状：启动报红色 TracebackModuleNotFoundError: No module named 'accelerate'（或同类导入错误）；或者能启动，但日志里挂着WanVideoWrapper WARNING: HuMo nodes not available这类告警。

判定命令：

pip list | grep -Ei "diffusers|accelerate|peft|gguf|sentencepiece"

判定标准：输出版本低于下表下限即不兼容；一条都不输出，说明依赖装进了错误的 Python 环境（最常见：装进系统 Python，而 ComfyUI 用的是自带 Python）。

修复：用 ComfyUI 自己的 Python 重装，requirements.txt 里的下限是项目实际验证过的最小版本：

pip install -r ComfyUI/custom_nodes/ComfyUI-WanVideoWrapper/requirements.txt

Windows portable 版换成内置解释器（readme.md Installation 一节的原命令）：

python_embeded\python.exe -m pip install -r ComfyUI\custom_nodes\ComfyUI-WanVideoWrapper\requirements.txt

预期输出：末尾Successfully installed ...。顺手验证一下 CUDA 是否真的接上了：

python -c "import torch; print(torch.cuda.is_available(), torch.__version__)"

判定标准：第一列必须打印True。若是False，装的是 CPU 版 PyTorch，视频生成慢到不可用，优先换 CUDA 构建，别的都不用调。

⚠️ 依赖轴两个坑

• 别照搬网传教程里的固定旧版本（如diffusers==0.23.1），照 requirements.txt 的下限装
• 装完重启 ComfyUI，日志搜WanVideoWrapper WARNING：有输出就按告警内容给对应可选模块补依赖，核心工作流不受影响

模型文件轴：下拉框为什么找不到它

症状：刚下载的模型不出现在WanVideoModelLoader下拉框；或下载"完成"后文件小得反常。

判定命令：

ls -lh ComfyUI/models/diffusion_models ComfyUI/models/text_encoders

判定标准：主模型在 GB 量级、文本编码器在数 GB 量级；出现 0 字节或几十 KB 的"大模型"文件，就是下载中断，重新下载。

修复：对照上一节的目录表把文件挪对位置——diffusion_models/放主模型（含.gguf），text_encoders/放 UMT5，clip_vision/放 CLIP vision，vae/放 VAE。

⚠️ 模型轴两个坑

• 主模型 5-20GB，先核对文件大小再排队，别等运行时才发现文件损坏
• README 作者个人推荐 fp8 scaled 版（显存占用更低），也给出对应模型仓库；文本编码与 CLIP vision 也可以直接复用 ComfyUI 原生 loader，不必重下一套

显存轴：CUDA out of memory 往哪查

症状：采样中途CUDA out of memory；或"为什么比昨天费显存"式的更新后首跑飙高。

判定：跑一次，nvidia-smi记录峰值，对照下一章参数表判断离溢出还有多远。

修复（从轻到重三步走）：

1. 调大blocks_to_swap——把尾部 transformer blocks 挪到 CPU，用的时候再换回来，输出参数不变
2. 调大offload_percent——按参数比例 offload，比 block swap 激进但更慢
3. 换 fp8 或 GGUF 量化模型

另外有一种和模型无关的显存异常：更新模型代码后，新输入尺寸的首跑显存明显偏高（readme.md 指出在 Windows 上最常见），重跑一次、缓存建立后自动恢复。仍复现就清编译缓存：

rm -rf ~/.triton ~/.cache/torchinductor_$USER

Windows 对应目录：C:\Users\<用户名>\.triton与C:\Users\<用户名>\AppData\Local\Temp\torchinductor_<用户名>。判定标准：清完重跑两次，峰值回落到与上次更新前同一量级即排除此项。

参数调优：显存、速度、画质怎么取舍

调参目标只有一条：峰值显存留出 1-2GB 余量，同时不动输出分辨率和帧数。

很多人以为显存不够只能牺牲分辨率，实际上block swap 让你原样保持 512x512x81：readme.md 实测 14B 模型 offload 20/40 blocks 约 16GB 跑完该规格。参数全部来自 nodes_model_loading.py 的节点定义，tooltip 就是官方注释：

长视频走分段而不是硬扛：上下文窗口节点（context_windows/context.py）把长视频切成窗口滚动生成。README 实测：1.3B T2V 生成 1025 帧、窗口 81 帧、重叠 16 帧，5090 显卡显存低于 5GB，耗时 10 分钟——这是"显存不够先分段、不是先降分辨率"的直接证据。

用了 LoRA 之后显存基线会变（README 更新记录）：未合并的 LoRA 权重现在挂成模型块的 buffer，跟随 block swap 一起换出；副作用是不开 block swap 时 LoRA 全量占显存。README 给的换算例子：1GB LoRA + 14B（40 blocks），单块增大约 25MB，swap 20 块共多占约 500MB，多 swap 2 块即可补偿。

速查：高频错误表与排查决策树

遇到报错先查表，表里对不上再走决策树。

实战案例：音频驱动口型与视频超分

案例 1：人物图 + 音频出同步口型视频（HuMo）

输入：一张人物图（仓库示例 human.png，1280x720）+ 一段音频。官方工作流 wanvideo_2_1_14B_HuMo_example_01.json，节点实现在 HuMo/nodes.py。

步骤：

1. 导入该 JSON，确认 HuMo 节点的图像、音频两个输入已接上
2. 音频编码由 HuMo/audio_proj.py 完成，工作流内已接好，无需手动配置
3. Queue Prompt

预期输出：mp4 时长与音频一致，口型随发音动作。口型对不上时先查音频采样率与视频帧率设置，而不是怀疑模型。

案例 2：FlashVSR 给低分辨率视频补清晰度

输入：低清视频帧序列（仓库 example_inputs/ 里的人像图可作测试素材）。官方工作流 wanvideo_1_3B_FlashVSR_upscale_example.json。

步骤：导入 JSON → 视频加载器接低清源 → 接 FlashVSR 节点链 → 输出。两个关键节点见 FlashVSR/flashvsr_nodes.py：

• WanVideoAddFlashVSRInput：strength取值 0.0-2.0、默认 1.0，控制低清 latent 的注入强度
• WanVideoFlashVSRDecoderLoader：解码器模型从ComfyUI/models/vae目录加载，精度可选fp16/fp32/bf16

预期输出：同场景的高清视频，边缘与纹理细节增强；放大效果不满意时优先调strength。

下一步往哪深入

• 控制类工作流：VACE、Fun-Control、ReCamMaster、Uni3C（含相机轨迹控制 fun_camera/），example_workflows/ 里都有现成 JSON，直接导入改参数
• 源码：transformer 结构看 wanvideo/modules/model.py，调度策略看 wanvideo/schedulers/
• 省显存进阶：把 LoRA 补偿、prefetch 调参与上下文窗口分段组合使用，参数取值全部以节点 tooltip 与 readme.md 的实测记录为准

【免费下载链接】ComfyUI-WanVideoWrapper项目地址: https://gitcode.com/GitHub_Trending/co/ComfyUI-WanVideoWrapper