ComfyUI 的六类目录与覆盖优先级：`--base-directory` 和五个单项参数谁说了算
装完 ComfyUI 之后迟早会遇到一件事：系统盘塞不下了。模型往 D 盘搬，输出往 NAS 上写，临时文件想扔到一块便宜的机械盘上，用户配置又希望跟着人走而不是跟着代码走。ComfyUI 为这件事准备了两套参数，一套是「一把抓」，一套是「精确覆盖」，它们可以同时出现在一条命令里——而同时出现时谁赢、哪个路径写错了会当场报错、哪个写错了会一声不吭地生效，这几件事决定了你是十分钟搞定还是排查半天。
下面的参数名、默认值和 help 语义，一律以 ComfyUI v0.31.0（核对日 2026-08-09）的 comfy/cli_args.py 为准。ComfyUI 的版本节奏很快，参数和默认值都会变，看到本文和你机器上 python main.py --help 的输出不一致时，以你自己那份输出为准。
一、先认清「六类目录」这个划分
--base-directory 的 help 说得很明确：它一次性设置 models、custom_nodes、input、output、temp、user 这六类目录的基准目录。也就是说，ComfyUI 眼里的可搬迁状态被切成了这六块：
| 目录类别 | 大致职责 |
|---|---|
models | 模型文件所在的根目录 |
custom_nodes | 自定义节点所在的目录 |
input | 工作流读取的输入文件目录 |
output | 生成结果的输出目录 |
temp | 临时文件目录，默认在 ComfyUI 目录内 |
user | 用户数据与配置目录 |
这个划分本身就是一条有用的信息：它告诉你 ComfyUI 认为哪些东西是「实例状态」而不是「程序代码」。你要做多实例、要把整套东西挪到另一块盘、要在容器里把状态挂成一个卷，对着这六类去规划就不会漏。
二、覆盖优先级：单项赢，而且只有五个单项
v0.31.0 的目录相关参数一共是这些：
| 参数 | help / 源码要点 |
|---|---|
--base-directory | 一次性设置 models、custom_nodes、input、output、temp、user 六类目录的基准目录 |
--output-directory | 设置输出目录，Overrides --base-directory |
--temp-directory | 设置 temp 目录（默认在 ComfyUI 目录内），Overrides --base-directory |
--input-directory | 设置输入目录，Overrides --base-directory |
--user-directory | 绝对路径，设置 user 目录，Overrides --base-directory，会校验路径存在、是目录、可读 |
--models-directory | 设置 models 目录，覆盖 --base-directory 里的 models 文件夹，同样会校验 |
--extra-model-paths-config PATH [PATH ...] | 加载一个或多个 extra_model_paths.yaml 文件，可重复 append |
这张表要横着读两遍。
第一遍看 Overrides：五个单项参数的 help 里都写了「Overrides --base-directory」。所以优先级没有任何模糊空间——两者同时给时，单项参数赢。--base-directory 更像一个兜底的默认值，谁没被单项指定，谁就落到 base 底下。这也意味着你完全可以写「大部分搬到 D 盘，只有输出走 NAS」这种混搭，不需要把六个目录一个个手写。
第二遍看谁不在表里：六类目录中，custom_nodes 在这份参数清单里没有对应的单项覆盖参数。models、input、output、temp、user 各有一个，唯独自定义节点目录只能跟着 --base-directory 走。这是个容易被忽略的不对称——如果你的目标是「把自定义节点目录挪出去」，那么你没得选，只能用 --base-directory，并顺带接受其余五类也一起搬（除非再用单项参数把它们逐个拽回来）。反过来，如果你只是想搬模型，用 --models-directory 就够了，别动 base，免得把 custom_nodes 一起带走、再花时间想「我的节点怎么全没了」。
三、一个反直觉的差异：两类参数的路径校验强度不一样
这是本文最值得记住的一条。
--user-directory 和 --models-directory 会走 is_valid_directory 校验：路径必须已经存在、必须是一个目录、必须可读，三条里有一条不满足，这道校验就过不去。而 --base-directory 在源码里没有走这个校验。
由此推出两种性质完全不同的处境，排查时的动作也不同：
处境一：--models-directory 或 --user-directory 路径写错。 这种反而好办——校验不通过就是答案，去核对那个路径是不是真的存在、是不是被你写成了文件而不是目录、当前用户对它有没有读权限。Windows 上还要多看一眼盘符和网络映射盘：映射盘在服务或计划任务的上下文里未必可见，人肉双击资源管理器能打开，不代表进程能打开（这属于通用 Windows 运维经验，不是 ComfyUI 文档里的内容）。
处境二：--base-directory 路径写错。 因为它不走那道校验，你就不能指望它像上面两个参数一样替你把错路径拦下来。至于路径写错之后 ComfyUI 具体会有什么表现，官方 help 与 README 都没有写，本文不替它猜。但有一条判断依据是明确的：「启动没有因为路径被拦下」并不等于「路径写对了」——这两件事在 --base-directory 上是脱钩的，而在另外两个参数上是绑定的。
所以碰到处境二，别一头扎进节点或模型加载逻辑里去猜。先做一个动作：看启动日志里的 base 目录那一行。ComfyUI v0.26.0（2026-06-23）的更新里有一条就是「使用 --base-directory 时把 base 目录打进启动日志」（PR #13370）。也就是说，在 v0.26.0 及之后的版本上，你不需要猜 base 到底指到了哪里，日志会告诉你。把日志里那一行的路径复制出来，到文件管理器或 ls 里贴一遍，路径对不对立刻见分晓。
顺带一个版本提醒：如果你跑的是 v0.26.0 之前的版本，启动日志里没有这一行，那就只能靠核对命令行本身。这也是「引用版本相关结论必须带版本号」的现实理由——同一个排查动作，在旧版本上根本不存在。
四、--extra-model-paths-config 是另一套机制，别和目录参数混用思路
很多人把 --models-directory 和 extra_model_paths.yaml 当成同一件事的两种写法，其实它们解决的是不同问题。
--models-directory是搬家：告诉 ComfyUI「models 根目录换到这里」。--extra-model-paths-config是加搜索路径：加载一个或多个extra_model_paths.yaml，而且这个参数可以重复 append，多份配置能叠加。
README 里对这份 yaml 的定位是：仓库里带了 extra_model_paths.yaml.example，把它改名为 extra_model_paths.yaml 并编辑，就能设置模型搜索路径、与其它 UI 共享模型；在 standalone windows 构建里，这个文件位于 ComfyUI 目录下。
所以判断依据可以简化成一句话：模型只有一处、想整体换位置，用目录参数；模型分散在多处、或要和别的 UI 共用同一份权重，用 yaml。 后者能重复 append 这一点很实用——比如一份 yaml 描述本机 SSD 上的常用模型，另一份描述挂载的共享存储，需要哪几份就在命令行上叠哪几份，不用去改一个巨大的配置文件。
五、怎么组合：三种常见处境
处境 A：系统盘满了，整套状态搬到 D 盘。 目标是六类一起走，用 --base-directory 最省事，custom_nodes 也只有这条路。
处境 B：只有模型太大，其它都还好。 用 --models-directory，不要动 base。好处是自定义节点、user 配置、历史都留在原地，出问题时可变因素少。
处境 C：整体搬走，但输出要写到别的地方（比如共享盘或大容量盘）。 base 打底，再用 --output-directory 把 output 单独拽出来。这正是「单项 Overrides base」的典型用法：
python main.py --base-directory D:\ComfyData --output-directory E:\ComfyOutput
Linux / macOS 侧写法同理，只是路径分隔符和盘符不同：
python main.py --base-directory /data/comfy --output-directory /mnt/nas/comfy-output
以上为按官方参数语义组合的示例，未逐项实测，以官方文档与 --help 输出为准。路径里含空格时按你所用 shell 的惯例加引号，这属于通用命令行习惯，不是 ComfyUI 的特殊规定。
六、改完之后怎么验证
- 先看日志：v0.26.0 及以后，启动日志里有 base 目录那一行，核对它是不是你想要的位置。
- 再看落盘：跑一次工作流，去
--output-directory指定的位置确认文件确实写在那儿，而不是老目录。输出目录是最容易验证的一类，因为它有实实在在的产物。 - 最后看清单：模型列表能不能刷出来，自定义节点有没有加载。如果 models 空了但节点在，问题多半出在 models 侧（目录参数或 yaml）；如果节点也没了，那就要怀疑是不是整个 base 指错了地方。
这个「日志 → 落盘 → 清单」的顺序不是随便排的：它从最不依赖运行结果的证据开始，逐步走到需要跑一次才能看到的证据，能少跑几次是几次。
七、什么情况说明不是目录参数的问题
也给一条退出条件，免得一条道走到黑：
- 如果你根本没加任何目录参数，模型却读不到，那和覆盖优先级无关，去查模型文件本身放的位置对不对。README 的口径是小模型只需要把 ckpt/safetensors 放进
ComfyUI\models\checkpoints，很多大模型有多个文件、要按说明分别放进ComfyUI\models\下的对应子目录——多文件模型只放对了一个，现象也会像「模型没识别」。 - 如果
--models-directory或--user-directory给的路径没能通过校验，那是is_valid_directory在起作用，问题在路径本身（不存在 / 不是目录 / 不可读），不是优先级问题。这一类不用往覆盖关系上想。 - 如果模型能加载、只是输出找不到，先确认是不是被
--output-directory覆盖了 base——按 help 的 Overrides 声明，这两个参数同时存在时输出以单项参数为准。
最后提一句和目录无关但同属「Overrides 家族」的参数，方便你举一反三：--front-end-root 的 help 也写了 Overrides --front-end-version，并且同样会校验目录存在与可读。可以放心用的规律只有前半句——凡是 help 里写了 Overrides，就是一条明确的优先级声明，不用再去别处求证。至于校验，v0.31.0 里能确认走目录校验的就是 --user-directory、--models-directory、--front-end-root 这三个，别的参数 help 没写，就别替它假设有校验。看到新参数时先在 --help 输出里搜一下 Overrides 这个词，比翻文档快。
延伸阅读
- ComfyUI 的五个注意力实现参数怎么选，以及 xformers 在里面扮演什么角色
- 读懂 DynamicVRAM：它什么时候会被悄悄关掉
- ComfyUI
--fast的四个优化项，开之前要知道的
本文依据 ComfyUI 官方仓库（github.com/Comfy-Org/ComfyUI）的 README、comfy/cli_args.py、
release notes 与官方安全公告整理，核对日 2026-08-09，对应版本 v0.31.0；
文中引用的 issue 状态为该日期的快照。本文内容为官方文档与源码口径，非本机实测。
参数、默认值与功能随版本变动，请以官方文档与 python main.py --help 的实际输出为准。