采样预览不显示，先看这个参数

2026-08-09

装完 ComfyUI，跑第一张图，KSampler 节点上一片空白，进度条在走，但节点里什么都不显示。等结果出来了图是好的，就是中间那几十秒你完全不知道模型在画什么。

这个现象在群里问一次能收到八种回答：显卡不行、前端版本不对、要装某个自定义节点、把浏览器缓存清一下。绝大多数时候都不是。在 ComfyUI v0.31.0（核对日 2026-08-09）的 comfy/cli_args.py 里，--preview-method 的默认值就是 none。 也就是说，你没开预览，它当然不显示。

这个默认值挺反直觉的。装好一个可视化工作流工具，你的第一反应不会是”它默认把可视化的那一半关掉了”。但官方 README 的预览章节写得很直白：要用 --preview-method auto 来启用预览。 默认安装自带一个低分辨率的快速 latent 预览方式，但你得显式把开关打开它才会用上。

一、先确认是不是这个原因

排查这类问题最忌讳的就是照着别人的截图对号入座。下面三个动作都能自己跑，不用猜。

第一步，把你实际的启动命令翻出来看一眼。 注意是”实际的”，不是你记忆里的。

Linux / macOS：如果你是手敲 python main.py 启动的，直接看命令历史；如果套了一层 shell 脚本，把脚本打开看调用 main.py 的那一行。
Windows：便携整合包通常是靠目录里的 .bat 脚本启动的，参数要加在那个脚本里调用 main.py 的那一行后面。各家整合包的脚本文件名不一样，我没有依据告诉你确切叫什么，自己打开目录看一下。

重点是确认这一行里有没有出现 --preview-method。没有，那当前就是源码默认的 none。

第二步，用 --help 确认这个参数在你这个版本上还叫这个名字。

python main.py --help

ComfyUI 的参数会随版本变动，主仓库里的前端每两周更新一次，参数表也不是一成不变的。养成习惯：任何一篇教程（包括这篇）给你的参数名，都以你本机 --help 的实际输出为准。

第三步，把这两个预览相关参数的官方语义看清楚。 事实卡范围内跟本篇直接相关的就这两行，其它 CLI 参数这里不铺开：

参数	类型 / 默认	help 语义
`--preview-method`	枚举 `LatentPreviewMethod`，取值 `none` / `auto` / `latent2rgb` / `taesd`，源码默认 `NoPreviews`（即 `none`）	选择采样过程中的 latent 预览方式
`--preview-size`	int，默认 `512`	采样节点的最大预览尺寸

四个取值里，none 就是当前的默认（不预览），auto 是 README 明确让你加的那个，latent2rgb 和 taesd 是另外两个合法取值。这里要克制一句：除了 taesd 需要额外下载解码器文件这一点，README 与源码没有再给这几个取值之间的其它说明，所以我不打算替它们编解释。README 明说的只有两件事：默认安装自带的是一个低分辨率的快速 latent 预览方式；想要更高质量的预览要另外准备 TAESD 的解码器文件——下一节说。

二、官方给的处置

最小改动是把 auto 加上：

python main.py --preview-method auto

Windows 便携包的话，就是在 bat 里那条调用 main.py 的命令末尾补上同样的 --preview-method auto，然后重新双击 bat。注意不是在网页里点某个设置项——这是启动参数，改完必须重启后端进程才生效。

如果你想直接指定方式而不让它 auto，把值换成 latent2rgb 或 taesd 即可。但 taesd 有前置条件：它需要 TAESD 项目的解码器文件。 README 给的做法是下载这四个文件：

taesd_decoder.pth
taesdxl_decoder.pth
taesd3_decoder.pth
taef1_decoder.pth

放进 models/vae_approx 目录，重启，再用 --preview-method taesd 启动。

这里有个容易翻车的地方：如果你用 --base-directory 或 --models-directory 改过模型根目录，那 vae_approx 要落在实际生效的那个 models 目录下面，而不是 ComfyUI 源码目录里那个。README 没有专门就预览目录说这件事，这是按参数语义推的；拿不准就先别动目录参数，用默认路径试一次，成功了再谈搬家。

顺带一提，README 对模型目录的通用说法是”按各模型说明放进对应子目录”，models/vae_approx 是 TAESD 预览解码器明确指定的位置，别跟放普通 VAE 的 models/vae 搞混了。

一条把上面几件事组合起来的示例：

python main.py --preview-method taesd --preview-size 512

以上为按官方参数语义组合的示例，未逐项实测，以官方文档与 --help 输出为准。

三、改完怎么验证

我要先说一句可能让你不太满意的话：我没有依据告诉你启动日志里会打印哪一行来确认预览已启用。 我们这批内容全部来自官方仓库的 README 与 comfy/cli_args.py，没有做本机实测，编一行”看到 Using taesd preview 就对了”这种话是很容易的，但那是骗人。

能踏实做的验证是这几件：

先把值本身抄对。 --preview-method 在源码里是枚举 LatentPreviewMethod，合法取值只有 none / auto / latent2rgb / taesd 这四个，手滑写成 tasesd 就不在枚举里了。改完之后回头逐字母核一遍你敲进去的那个词，这一步花不了十秒，却能省掉后面一整轮无效排查。
重新跑一次采样，而且要跑一张”没跑过的”。 这条比参数本身还重要，理由见下一节——ComfyUI 只执行相对上一次发生变化的那部分图，你原样再提交一遍，它可能根本不会重新采样，自然也不会有预览过程给你看。改一下 seed 或提示词再排队。
用 taesd 时先确认文件真的在位。 四个 .pth 文件名一个字母都不能错，目录是 models/vae_approx。文件没到位就指定 taesd，问题的性质就从”没开预览”变成”开了但资源缺失”，别把两件事混着查。
想看更详细的运行日志，用 --verbose。 它可以不带值（等价于 DEBUG），也可以给一个等级，合法等级是 DEBUG、DETAIL、INFO、WARNING、ERROR、CRITICAL，控制台默认 INFO。加上它至少能让你看到进程在这一步有没有抛异常。其中 DETAIL 这一级是 v0.30.0 的「可配置 DETAIL 日志侧通道」（PR #15064）带来的，属于较新的等级，写进命令前先用 --help 确认你这个版本有它。另外 --verbose 的取值形式也别写错：它接受不带值、给一个 LEVEL、或者给 LEVEL FILE 两个值三种形式，组合不合法时源码给出的报错文案是 expects no values, a console LEVEL, or LEVEL FILE——看到这行就知道是自己参数写法的问题，不是预览的问题。

四、什么情况说明不是这个原因

这一节才是这篇文章相对”报错大全”的价值所在。以下几种迹象出现时，别再在 --preview-method 上打转了。

迹象一：你确认加了 --preview-method auto 并重启过，依然一片空白。

那就不是”没开”的问题了。这里如实引用一条公开记录：官方仓库 issue #11400 反映了「更新到最新版本后 KSampler 预览不再显示」这一现象，该 issue 创建于 2025-12-18，标签为 Potential Bug，截至 2026-08-09 仍为 open。

请注意三件事：Potential Bug 的字面含义是”疑似 bug”，不是官方已确认；这条 issue 至今没关闭，不代表已修复，也不代表官方已认可；而且我们没有读过这条 issue 的正文和评论，所以我不会告诉你它的复现步骤、根因或者社区有什么绕过办法——那些我一个字都不知道。它在这里的唯一作用是：让你知道”加了参数还是没有”这种情况客观存在过，你不是一个人在犯傻，可以停止怀疑自己的操作，转而去 issue 列表里按你的版本号搜同类记录。

迹象二：不只是没预览，是整个图好像根本没跑。

先别怪预览。ComfyUI 的执行模型在 README 的 Notes 里写得很清楚：只有输出端所有输入都正确的那部分图会被执行；只有相对上一次执行发生变化的部分会被执行——提交两次完全相同的图，只有第一次真正执行。所以”我点了排队，什么都没动”这件事，官方给的解释顺位是执行模型，不是预览开关。

顺着这条还有一个常见坑：Ctrl + B 是 bypass 选中节点，README 对它的解释是行为等同于该节点被移除、连线从中穿过重连。你要是不小心 bypass 了采样相关的节点，那当然什么预览都不会有。另外还有个 Ctrl + M 是静音，README 没有给它同等程度的语义说明，我就不替它编了，但两个快捷键挨得近，误触很正常，先按 Ctrl + Z 撤销看看。

如果你想强制每次都完整执行一遍来排除缓存因素，有个 --cache-none，它的 help 写的是降低 RAM/VRAM 占用、代价是每次运行都重新执行每个节点。仅用于排查，日常别一直挂着。

迹象三：预览出来了，但很小、很糊。

这跟”不显示”是两个问题，别混为一谈。--preview-size 默认 512，它管的是采样节点的最大预览尺寸；而 README 明说默认自带的那个 latent 预览方式本身就是低分辨率的快速方式，“糊”是它的设计取向。想要更高质量，走的是上面第二节的 TAESD 路线，不是把尺寸参数调大。

迹象四：后端一切正常，浏览器里其它 UI 元素也有点不对劲。

那更可能是前端的事。2024-08-15 起 ComfyUI 前端迁到了独立仓库 Comfy-Org/ComfyUI_frontend，编译产物发到 pypi 的 comfyui-frontend-package 作为依赖安装（v0.31.0 的 requirements.txt 里 pin 的是 1.48.7）；主仓库里的前端每两周更新一次，独立仓库则是每日发布。你可以用 --front-end-version Comfy-Org/ComfyUI_frontend@latest 取每日版，或者把 latest 换成具体版本号回退——help 注明这个命令需要联网去 GitHub releases 查询下载。README 也明说了：前端相关的 bug 与需求应该提到前端仓库，提错地方只会拖慢分流。

迹象五：你最近装了一堆自定义节点。

用 --disable-all-custom-nodes 起一次，不加载任何自定义节点，看预览是否恢复。要保留个别节点可以配合 --whitelist-custom-nodes NAME [NAME ...]。这是个纯粹的二分法动作：干净环境下正常，问题在扩展侧；干净环境下依旧空白，那就跟自定义节点无关，别继续在那边浪费时间。

最后一句劝告：排查预览的时候别顺手加 --fast。它的 help 原文注明那是一些未经测试、可能劣化质量的优化，用于测试新特性，用了可能让你的 ComfyUI 崩溃。在你连预览为什么不显示都还没搞清楚的时候，往启动命令里塞一个官方自己都标注”未经测试”的开关，只会让变量更多。一次只动一个参数，这条规矩在 ComfyUI 上尤其管用。

延伸阅读

本文依据 ComfyUI 官方仓库（github.com/Comfy-Org/ComfyUI）的 README、comfy/cli_args.py、 release notes 与官方安全公告整理，核对日 2026-08-09，对应版本 v0.31.0；文中引用的 issue 状态为该日期的快照。本文内容为官方文档与源码口径，非本机实测。参数、默认值与功能随版本变动，请以官方文档与 python main.py --help 的实际输出为准。