ComfyUI-WanVideoWrapper 的 WanVideo 视频生成完整指南：从装到出片一次解决 6 个卡点

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

ComfyUI-WanVideoWrapper 是 ComfyUI 上的 WanVideo 视频生成节点包，覆盖模型加载、采样、显存管理、上下文窗口长视频四类节点，内置 HuMo、VACE、ControlNet 等数十种扩展。本文按"先跑通、卡住自救"的路径走一遍：最短路径出片、显存三开关、报错原文速查和两个最小案例。

先验证你的显卡带不带得动：基线对照表

所有数据均取自仓库 readme.md 与 requirements.txt 原文，没有实测数据的地方以仓库 README 为准。

依赖版本下限（requirements.txt 原文）：

⚠️ 依赖必须装进 ComfyUI 的 Python。装进系统全局 Python 后，重启 ComfyUI 仍会报ModuleNotFoundError，这是第一高频问题。

跑通最短路径：从 clone 到第一个 mp4

第一步：装插件和依赖

cd ComfyUI/custom_nodes git clone https://gitcode.com/GitHub_Trending/co/ComfyUI-WanVideoWrapper pip install -r ComfyUI/custom_nodes/ComfyUI-WanVideoWrapper/requirements.txt

portable（Windows 免安装）版用内置 Python，路径见 readme.md Installation 一节：

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

应该看到什么：clone 后custom_nodes/下多出ComfyUI-WanVideoWrapper目录；pip 末尾打印Successfully installed ...。判定标准：装完后pip list中上述 5 个带下限的包版本号不低于下限即通过；低于下限用pip install --upgrade 包名补齐。

入口init.py 的加载规则值得知道：nodes、nodes_sampler、nodes_model_loading、nodes_utility、cache_methods五个必需模块，任何一个导入失败都会直接抛异常阻断启动；其余几十个扩展模块（HuMo、FlashVSR、ATI 等）失败只打印WanVideoWrapper WARNING: {模块名} nodes not available警告，不阻断核心流程。所以"某个扩展节点不见了"通常是该模块缺依赖，不是插件坏掉。

第二步：四个模型文件放进对应目录

目录由 ComfyUI 的folder_paths机制固定（readme.md Models 一节），放错目录下拉框里选不到：

关于 GGUF：nodes_model_loading.py 第 53 行把unet_gguf键挂到diffusion_models目录扫描，README 也写明 "GGUF models can now be loaded in the main model loader as well"。也就是说.gguf量化文件直接放进diffusion_models/，WanVideoModelLoader就能选中，小显存卡靠量化版省显存。

验证文件完整性：

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

应该看到什么：主模型 GB 量级、文本编码器数 GB 量级。判定标准：0 字节或几十 KB 的文件就是下载中断，重下即可，别指望运行时才发现问题。README 中作者个人推荐 fp8 scaled 版模型（显存占用更低），对应仓库地址在 README Models 一节。

第三步：导入官方示例工作流，出第一个视频

仓库自带 40 多份可导入工作流，按模型规模从小到大起步：

ls example_workflows | grep 1_3B

应该看到什么：wanvideo_1_3B_EchoShot_example.json、wanvideo_1_3B_FlashVSR_upscale_example.json等文件名。判定标准：把选中的 JSON 拖进画布后，每个 loader 节点的下拉框都能选到模型、连线完整无红框，即可以 Queue Prompt。预期输出：ComfyUI 日志滚动采样进度条，结束后ComfyUI/output/出现 mp4。

核心节点的默认参数（源码可查，出问题先对照）：

load_device的 tooltip 明确提示：大模型不要选main_device，除非你有 48GB+ 显存；num_frames的步长为 4，即帧数必须满足 4n+1。

显存爆掉时：三个 offload 开关和实测数字

WanVideoWrapper 提供两种互斥的 offload 机制（loadmodel里有 assert：两者同时接入会直接报错 "Can't use both block_swap_args and vram_management_args at the same time"），外加一个弥补速度的预取开关：

调参流程：跑一次，用nvidia-smi记录显存峰值，再决定 swap 多少 blocks。

nvidia-smi

应该看到什么：采样期间Memory-Usage的占用数字。判定标准：峰值距离显卡总显存留出 1-2GB 余量即安全；OOM 就调大blocks_to_swap，每加 1 个 block 观察一次。

两个容易忽略的显存来源：

• 未合并的 LoRA。README "Update notification" 一节说明：新版 LoRA 权重以 buffer 形式挂到对应 block 上，遵循 block swap；但如果你没用 block swap，LoRA 会全部常驻显存，比旧版更吃显存。README 给了具体算例：1GB 未合并 LoRA + 14B 模型 swap 20 blocks 时，单 block 增大约 25MB，总占用多 500MB，补偿方法是多 swap 2 个 blocks。
• GGUF 模型的两个硬限制：quantization必须为disabled（否则报 "Quantization should be disabled when loading GGUF models."），且不支持 LoRA merge（否则报 "GGUF models do not support LoRA merging, please disable merge_loras in the LoRA select node."），这两条在 nodes_model_loading.py 第 1132-1137 行可直接查。

报错时先查这三处：报错原文速查

⚠️ 判定优先级：先看日志有没有红色 Traceback → 没有再看下拉框缺不缺模型 → 都没有再看是不是运行时 OOM。三处都排查完，多数问题就能定位。

两个最小案例：说话视频与长视频分段

案例一：一张图 + 一段音频，出说话人视频

输入：一张人物图（可用仓库自带 example_workflows/example_inputs/human.png）和一段音频。

关键步骤：

1. 导入官方示例 example_workflows/wanvideo_2_1_14B_HuMo_example_01.json，节点实现在 HuMo/nodes.py
2. 确认 HuMo 节点的图像、音频输入已连接；音频编码由 HuMo/audio_proj.py 完成，工作流内已接好
3. Queue Prompt

预期结果：输出与音频时长一致的 mp4，口型与发音对齐。判定标准：视频时长 ≈ 音频时长；若口型不同步，先查音频采样率与帧率设置，不要怀疑模型。

案例二：1025 帧长视频，用上下文窗口分段生成

输入：1.3B T2V 模型 + 长 prompt。

关键步骤：

1. 在 nodes.py 的WanVideoContextOptions（第 1894 行）节点设置分段：默认context_frames=81、context_stride=4、context_overlap=16（注意 tooltip 提示 latent 空间 4 帧合 1，填的是像素帧数）
2. 把context_options接入WanVideoSampler的context_options端口，num_frames直接填 1025
3. 分段与融合逻辑在 context_windows/context.py

预期结果：README "Context window test" 一节的实测口径——1.3B T2V 模型、窗口 81 帧、重叠 16 帧，生成 1025 帧显存低于 5GB，RTX 5090 上耗时 10 分钟。判定标准：总帧数为 1025 且分段融合处无明显跳变。

三条反直觉经验，以及下一步往哪走

1. 多数人的假设：显存不够就降分辨率、减帧数。实际做法：先保持完整参数，调大blocks_to_swap并把prefetch_blocks设为 1，速度损失基本被预取抵消。仓库内的依据：README 实测 14B 模型 512x512x81、offload 20/40 blocks 约 16GB；nodes_model_loading.py 第 306 行 prefetch 的官方 tooltip。

2. 多数人的假设：长视频就该把num_frames拉大硬跑。实际做法：用上下文窗口分段生成，帧数直接填 1025 也不爆显存。仓库内的依据：README Context window test 实测 1025 帧 < 5GB；context_windows/context.py 的滑动窗口与融合实现。

3. 多数人的假设：TeaCache 阈值越小跳步越少、结果越稳。实际做法：新版阈值是旧版的 10 倍，经验区间 0.25-0.30，阈值过低反而会跳过早期步、破坏运动连贯性。仓库内的依据：README "TeaCache" 一节明确写 "with the new version the threshold values should be 10x higher" 和 "Range of 0.25-0.30 seems good"。

至此，装环境、放模型、出片、显存调参、报错定位的主干路径已经走完，速查表建议留在手边。下一步两个深入方向：控制类玩法看 example_workflows/ 里的 VACE、Fun-Control、ReCamMaster 系列工作流；想改采样与 VRAM 逻辑，读 wanvideo/schedulers/ 与 wanvideo/modules/model.py 的调度器和模型实现。

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