ComfyUI视频模型存储路径解析：最佳实践与避坑指南
把模型文件随手一扔，节点就报错；换个电脑，路径全红。这篇笔记把 ComfyUI 的视频模型到底该放哪儿、怎么放、放错了怎么救，一次性讲透。全部基于 v0.2.2 稳定版实测，代码可直接复制跑。
1. 核心概念：先认清“家”在哪
ComfyUI 的目录约定非常死板，视频模型（包括.ckpt、.pt、.pth、.safetensors）只能被扫描到以下两处：
ComfyUI/models/video_models/ComfyUI/models/checkpoints/（老版本兼容，但官方已不推荐）
扫描逻辑在comfy/model_management.py的get_model_paths()里写死：递归深度 1，只认*.pt/*.pth/*.ckpt/*.safetensors后缀，其余一律无视。
因此，把文件直接拖进models/video_models/是最省心、最不容易翻车的做法。
目录结构一览：
ComfyUI/ ├── models/ │ ├── checkpoints/ # 普通 SD 权重 │ ├── clip_vision/ # CLIP 视觉 │ ├── video_models/ # 本文主角 │ └── … ├── custom_nodes/ ├── config.json # 关键配置文件 └── …2. 痛点分析：90% 的报错都是路径写错
把社区里 200+ 条 issue 翻完，高频踩坑就这四类：
相对路径写错
Windows 用户习惯.\models\video_models\xxx.ckpt，结果节点里填的是./models/video_models/xxx.ckpt，正反斜杠混用，Python 直接FileNotFoundError。权限问题
Linux 服务器上多人共用，模型文件root:root 600，ComfyUI 以普通用户启动，扫描到文件却读不到，日志只提示model load fail，一脸懵。跨平台兼容性
在 macOS 上打包路径，传到 Ubuntu 发现大小写不一致，VideoSynthModel变成videosynthmodel，节点同样加载失败。缓存残留
旧模型被覆盖后，ComfyUI 依旧加载缓存里的*.cache文件，导致“明明换了权重，出图却不变”的灵异事件。
3. 技术方案：把“死”路径变成“活”配置
3.1 用 config.json 自定义扫描目录
在 ComfyUI 根目录新建或修改config.json，加入extra_model_paths字段即可追加扫描目录，无需改源码。
{ "extra_model_paths": { "video_models": [ "/data/shared/comfyui_video", "/mnt/nas/ai_models/video" ] } }重启后，ComfyUI 会把两处远端目录软合并到models/video_models/的可见列表里，节点下拉框直接出现远端权重，逻辑上就像本地一样。
3.2 环境变量临时覆盖
CI 或云函数场景，写死路径不灵活，用环境变量最干净。启动前 export：
# Linux / macOS export COMFYUI_VIDEO_MODELS=/tmp/extra/video # Windows PowerShell $env:COMFYUI_VIDEO_MODELS="C:\ai\extra_video"然后在 Python 端动态读取：
import os, pathlib from comfy.model_management import get_model_paths # 取环境变量，若无则回退到默认 extra_video = os.getenv("COMFYUI_VIDEO_MODELS") if extra_video: extra_video = pathlib.Path(extra_video).resolve() # 把新目录插到扫描列表最前 get_model_paths().insert(0, extra_video)这样同一份代码，在本地、Docker、Slurm 集群都能即插即用，零硬编码。
4. 代码示例：动态加载“任意位置”的模型
下面这段脚本演示了完全脱离默认目录，从任意路径加载视频模型并喂给节点的最小可复现例子。复制到custom_nodes/即可运行。
import torch import folder_paths from pathlib import Path class LoadVideoModelExternal: @classmethod def INPUT_TYPES(cls): return { "required": { "model_path": ("STRING", {"default": "/tmp/my_video.ckpt"}), } } RETURN_TYPES = ("VIDEO_MODEL",) FUNCTION = "load" CATEGORY = "video" def load(self, model_path): p = Path(model_path).expanduser().resolve() if not p.exists(): raise FileNotFoundError(f"模型不存在: {p}") # 按需加入扫描缓存，避免二次读盘 if str(p.parent) not in folder_paths.folder_names_and_paths["video_models"]: folder_paths.folder_names_and_paths["video_models"].append(str(p.parent)) # 真正加载 sd = torch.load(p, map_location="cpu") return (sd,) NODE_CLASS_MAPPINGS = { "LoadVideoModelExternal": LoadVideoModelExternal }使用技巧
- 把
model_path暴露成输入端口，工作流里直接拖字符串，无需重启 ComfyUI。 - 对
.safetensors可换成safetensors.torch.load_file，速度更快。
5. 生产环境考量：多人协作怎么不踩脚
统一 UID 与掩码
新建comfy用户组，所有模型chown -R comfy:comfy，掩码设002，保证同组可写。只读挂载 + 符号链接
大文件放 NFS，挂载只读；各用户在自己models/video_models/里ln -s /mnt/nas/xxx.ckpt，既省空间又互不干扰。版本锁
给每个模型加sha256sum校验文件，CI 启动时比对，防止“同名不同内容”导致可复现性灾难。
6. 避坑指南：Windows 与 Linux 差异化生存
| 场景 | Windows 坑点 | Linux 坑点 | 建议 |
|---|---|---|---|
| 路径分隔符 | 反斜杠\需双写或加r"" | 正斜杠/ | 统一用pathlib.Path，自动处理 |
| 大小写 | 不敏感 | 敏感 | 模型文件名、节点参数全部小写 |
| 符号链接 | 需要管理员权限 | 默认支持 | Win 上用mklink /D需管理员控制台 |
| 中文空格 | 允许但易乱码 | 允许 | 杜绝中文与空格，用_替代 |
真实故障复现
用户把模型放D:\AI 模型\video\hello.ckpt，节点填"D:\AI 模型\video\hello.ckpt"，结果 Python 字符串把\v当成垂直制表符，直接报错UnicodeDecodeError。
解决：改成r"D:\AI 模型\video\hello.ckpt"或者干脆pathlib.Path("D:/AI 模型/video/hello.ckpt")。
7. 小结与开放式思考
路径问题看似琐碎，却能在凌晨三点让工作流彻底崩盘。把“模型放哪”写成文档、写进脚本、写进 CI，比任何炫酷节点都更能保住头发。
留一个问题给你：当团队规模再扩大，视频模型动辄 10GB+，单机硬盘成为瓶颈，你是否会考虑把models/video_models/指向分布式对象存储（如 s3、minio）并通过 FUSE 挂载？还是有更优雅的按需流式加载方案？欢迎分享你的思路，一起把 ComfyUI 玩成“云原生”。
