ComfyUI 生成出黑图：官方口径里只有这三条线索
出黑图这件事最让人上头的地方在于：流程一路绿灯，节点没报错，进度条走完了，点开图是纯黑。没有异常栈可看，也就没有搜索关键词，于是很容易滑进「把网上十几种偏方挨个试一遍」的模式——换 VAE、换采样器、换显卡驱动、重装依赖，试到最后哪一步起了作用自己也说不清。
比较务实的做法是先把范围缩到「官方自己承认与黑图有关」的地方。在 ComfyUI v0.31.0（2026-08-08）这个时点上，把 comfy/cli_args.py、comfy/model_management.py 和 README 翻一遍，明确提到 black images 的位置只有三处。这篇就按这三处来，每一条都给出怎么确认、怎么处置、处置完怎么验证，以及——什么情况说明不是它。最后一条比前面几条都重要，它决定了你会不会在一条错路上耗一晚上。
线索一：--fp16-vae 的 help 里写着 might cause black images
这是三条里最直白的一条。在 v0.31.0 的 comfy/cli_args.py 中，VAE 精度是一组互斥参数：--fp16-vae、--fp32-vae、--bf16-vae 三选一，另有一个独立的 --cpu-vae（把 VAE 放到 CPU 上跑）。其中只有 --fp16-vae 的 help 文本带了一句警告：might cause black images。
注意这句话的措辞是「可能导致」，不是「一定会」。官方把它写进 help，等于提前告诉你：这个开关和黑图之间存在已知的关联，但没承诺什么条件下必然触发。所以它不是一个「不能用」的参数，而是一个「出黑图时第一个该被摘掉的嫌疑人」。
怎么确认是这个问题。 动作只有一个：把你实际用来启动 ComfyUI 的那条命令找出来，逐字看有没有 --fp16-vae。这里最容易漏的是你根本不是手敲命令启动的——桌面快捷方式的目标栏、一键包里的 .bat／.sh、别人给你的启动脚本、或者你半年前照着某篇教程加上去就忘了的那一串参数，都要翻开看。参数是不是自己写的，和它在不在生效，是两回事。
处置。 官方给的语义很清楚：这三个 VAE 精度参数互斥，你把 --fp16-vae 去掉，就回到不指定精度的默认路径；如果确实想显式指定，可以改成 --fp32-vae 或 --bf16-vae。另外还有一个 --cpu-vae，help 的意思就是让 VAE 在 CPU 上执行——它属于同一个环节的另一条路径，值得作为对照实验保留在手边。
处置后怎么验证。 别只看一张图。合理的做法是：只改这一个变量，其它一切（模型、提示词、种子、分辨率、采样器）保持不动，重跑同一张图。这里要提醒一句，comfy/cli_args.py 里 --deterministic 的 help 原文写得很老实——让 pytorch 尽量使用较慢的确定性算法，但这可能并不能在所有情况下让图像可复现。也就是说别指望加一个参数就能得到严格逐像素一致的对照组，你要观察的是「还黑不黑」这个二值结果，而不是细微差异。
什么情况说明不是这个原因。 如果你的启动命令里压根没有 --fp16-vae，那这条线索到此为止，别再往「VAE 精度」上使劲。这个判断很硬，因为官方把黑图与精度的关联只挂在了这一个开关上——--fp16-unet、--force-fp16（源码里它会连带把 fp16_unet 置真）、--fp16-text-enc 这些同族参数的 help 里都没有黑图相关的措辞。
线索二：启动日志里那条 xformers 高分辨率黑图告警
第二条线索不在参数里，在日志里。comfy/model_management.py 在检测到有问题的 xformers 版本时，会输出这样一条告警：
WARNING: This version of xformers has a major bug where you will get black images when generating high resolution images.
紧跟着的一句是官方给的处置意见：
Please downgrade or upgrade xformers to a different version.
这条告警的价值在于它把「高分辨率」这个条件写进去了。如果你的现象恰好是「小图正常、放大分辨率就黑」，而日志里又有这一条，那基本可以停止猜测——这不是玄学，是官方明确指向的 xformers 版本问题。
怎么确认。 三个可执行动作：
- 翻启动日志的开头几十行，找有没有上面那句
WARNING。同一段日志里还会打印xformers version: {版本}这一行，把版本号记下来，它是你后面换版本的基准。 - 日志刷太快看不清就把它落到文件里。
--verbose支持不带值、给一个 LEVEL、或者给LEVEL FILE两个值，合法等级是DEBUG、DETAIL、INFO、WARNING、ERROR、CRITICAL，不带值等价于 DEBUG，控制台默认等级是INFO。另外注意一个容易踩的默认值：ComfyUI 的正常进程输出默认走 stderr，你如果习惯性写> log.txt只重定向 stdout，很可能捞了个空文件，需要的话可以用--log-stdout把它切到 stdout。 - 做一次分辨率对照：同一工作流跑一个明显更小的尺寸。如果小图正常大图黑，这条线索的可疑度就上去了。
处置。 官方文案给的方向就两个字：升级或降级 xformers 到另一个版本。它没有指定「换到哪个版本」，我们也没有任何版本对照数据，所以这里不能替你圈一个「安全版本号」。你能做的是拿日志里那行 xformers version: 当起点，向上或向下换一档，重启后再看告警还在不在。
另外 comfy/cli_args.py 里有一个独立的 --disable-xformers，可以用来做纯粹的「摘掉变量」实验。这里有个很多人不知道的连带效应：注意力实现是一组五选一的互斥参数（--use-split-cross-attention、--use-quad-cross-attention、--use-pytorch-cross-attention、--use-sage-attention、--use-flash-attention），其中前两个的 help 都明确注明 Ignored when xformers is used。意思是你如果一边在用 xformers、一边加了 --use-split-cross-attention 想换条路走，这个参数是被无视的，你以为换了实现其实没换。要真的绕开 xformers，得用 --disable-xformers。
处置后怎么验证。 重启，先看那条 WARNING 有没有从日志里消失，再跑原来那张出黑图的高分辨率图。两件事都要看：告警消失但图还黑，说明版本换掉了但问题不在这；告警还在，说明你换的这一版仍在官方判定的问题范围内。
什么情况说明不是这个原因。 日志里没有这条 WARNING，就不要往 xformers 上想；小图同样黑（不满足「高分辨率」这个前提），也不该往这条上靠；--disable-xformers 之后仍然出黑图，这条线索同样可以划掉。
线索三：--force-upcast-attention 的 help 留了个上报入口
第三条最微妙。comfy/cli_args.py 里有一组关于 attention upcasting 的互斥参数：
--force-upcast-attention：强制开启 attention upcasting，help 里跟了一句——如果它修好了黑图，请上报。--dont-upcast-attention：关闭所有 upcasting，help 里写得很直接：除调试之外应该没有必要。
前者那句话值得多读两遍：help 没有写成「遇到黑图就加这个」，而是写成「如果它修好了黑图，请上报」。需要说明的是，这是我们对 help 措辞的读法，官方没有在文档里进一步解释为什么这么写，也没有给出这个开关与黑图之间的适用条件。所以对读者而言，它更接近一个待验证的方向，而不是一条现成的处方。
怎么用它。 把它当探针，不是当解药：在保持其它变量不变的前提下加上 --force-upcast-attention，重启，跑同一张图。黑图消失，你就得到了一个明确的观测结果，而这正是 help 里请你上报的东西。黑图没消失，说明这个方向对你这台机器不成立，把参数摘掉，别让它长期留在启动命令里。
反方向的 --dont-upcast-attention 不建议在排查黑图时随手打开。它的 help 自己就说了「除调试外应该没必要」，你在一个已经异常的环境里再关掉一层保护性处理，只会让变量更多。另外要注意这两个参数在 comfy/cli_args.py（v0.31.0）里属于同一个互斥组，不能同时给，所以不存在「两个都加上试试」这条路。
处置后怎么验证。 这条线索的验证要比前两条更严格，因为它不像 xformers 那条有现成的告警可以对照——comfy/model_management.py（v0.31.0）里我们能核到的启动日志文案，是 Set vram state to:、xformers version: 这类，没有一条是专门用来指示 attention upcasting 有没有生效的，你能观察的就只有图本身。所以对照实验要做得干净：只加这一个参数，模型、提示词、种子、分辨率、采样器全部不动，重跑那张原本出黑图的图；确认结果之后，把参数摘掉再跑一次，看黑图是不是又回来了。一加一减都对得上，这个观测结果才算站得住，也才是 help 里请你上报的那种信息。同样要记得 --deterministic 的 help 已经声明了「可能并不能在所有情况下让图像可复现」，你要比对的是黑与不黑，不是像素级差异。
什么情况说明不是这个原因。 加上之后没变化，就是没变化，不要接着叠加其它开关去「配合」它——三条线索是彼此独立的判定，不该混着开。
顺序、以及一条经常被忽略的干扰项
三条线索建议按成本从低到高排：先看启动命令里有没有 --fp16-vae（零成本，看一眼就知道），再翻日志找 xformers 告警（零成本，日志本来就在），最后才是加 --force-upcast-attention 做一次探针实验（需要重启和一次完整生成）。
排查期间还有两个参数值得顺手清一清，它们不是黑图的官方原因，但会让你的对照实验不干净：
--fast。help 原文说得非常坦白：这是一些未经测试、可能劣化质量的优化，用于测试新特性，用了可能让你的 ComfyUI 崩溃。不带参数等于全开，也可以传具体项（合法项是fp16_accumulation、fp8_matrix_mult、cublas_ops、autotune）。既然官方自己标了「可能劣化质量」，排查画面异常时它就该是第一个被摘掉的。--fp16-intermediates。help 里明确标了 Experimental，作用是让节点之间的中间张量用 fp16 而不是 fp32。带 Experimental 标记的东西，出现在一个正在排查的环境里就是噪声。
另外，如果你想知道「黑是从采样阶段就黑，还是解码之后才黑」，--preview-method 可以给一点观察窗口：它的取值是 none / auto / latent2rgb / taesd，源码里的默认是 none（也就是默认你什么中间过程都看不到），README 说默认安装自带一个低分辨率的快速 latent 预览方式，用 --preview-method auto 即可开启。需要说明的是：官方并没有把开预览列为黑图排查步骤，这只是按参数语义推出来的一个观察手段，你据此得到的判断请自己承担。
其它黑图原因，官方文档里没有，本文不猜
这一节是这篇文章里最重要的一段。
网上关于 ComfyUI 黑图的说法远不止三条——某个 VAE 权重不匹配、某张显卡的某个驱动版本、某类采样器组合、某个自定义节点、某个模型架构的特殊处理，每一种听起来都煞有介事。我们在 comfy/cli_args.py、comfy/model_management.py 和 README 里能核到的、明确写着 black images 的地方，只有上面三处。除此之外的原因，我们没有依据，因此这里一条都不写。
这不是谦虚，是排查纪律。你手上有一个只会给出「黑」或「不黑」的二值信号，能做的实验次数有限，把有限的实验花在有官方依据的三个变量上，比挨个试网上的偏方要划算得多。三条都试完仍然黑，正确的下一步不是继续猜，而是把变量收干净：--disable-all-custom-nodes 可以让 ComfyUI 不加载任何自定义节点，配合 --whitelist-custom-nodes 可以在此基础上只放行指定的目录，这组参数天然适合做二分排查。需要说明的是，官方并没有把这一步写成黑图的排查步骤，它只是一个通用的「先确认原生环境是否复现」的做法——但至少能告诉你，问题在不在 ComfyUI 本体范围内。
如果连原生环境都复现，那你手上就有了一个干净的最小复现，这时候去官方仓库提 issue 才有意义。顺带提醒一句：ComfyUI 的前端自 2024-08-15 起已经迁到独立仓库 Comfy-Org/ComfyUI_frontend，README 明确说前端相关的 bug 与需求应该提到前端仓库去。
最后重复一遍版本纪律：以上全部结论对应 v0.31.0（2026-08-08）时点的 comfy/cli_args.py 与 comfy/model_management.py。ComfyUI 大约每两周一个版本，参数名、默认值、告警文案都可能变。你真正该信的不是这篇文章，而是你那台机器上 python main.py --help 的实际输出。
延伸阅读
本文依据 ComfyUI 官方仓库（github.com/Comfy-Org/ComfyUI）的 README、comfy/cli_args.py、
release notes 与官方安全公告整理，核对日 2026-08-09，对应版本 v0.31.0；
文中引用的 issue 状态为该日期的快照。本文内容为官方文档与源码口径，非本机实测。
参数、默认值与功能随版本变动，请以官方文档与 python main.py --help 的实际输出为准。