[{"data":1,"prerenderedAt":965},["ShallowReactive",2],{"content-/zh/basic-tutorial/trouble-shooting":3},{"id":4,"title":5,"body":6,"description":16,"extension":958,"meta":959,"navigation":960,"path":961,"seo":962,"stem":963,"__hash__":964},"content/zh/basic-tutorial/trouble-shooting.md","ComfyUI 常见问题与排查指南（简体中文完整版）",{"type":7,"value":8,"toc":927},"minimark",[9,13,17,20,45,48,53,56,112,114,118,123,137,143,154,159,223,225,229,234,238,246,250,295,297,301,305,317,319,323,327,332,336,347,352,459,465,467,471,475,486,490,518,520,524,528,539,543,562,564,568,572,584,588,600,602,606,610,624,628,639,641,645,649,657,661,669,671,675,679,683,694,698,709,711,715,719,730,734,745,747,751,755,766,770,784,786,790,794,798,809,811,815,819,830,834,845,847,851,856,860,875,877,881,886,890,901,903,906,923],[10,11,5],"h1",{"id":12},"comfyui-常见问题与排查指南简体中文完整版",[14,15,16],"p",{},"这是一份全面的 ComfyUI 故障排查参考手册，从安装失败到生成报错，为新手与进阶用户提供一步步可操作的解决方案。",[14,18,19],{},"我们涵盖：",[21,22,23,27,30,33,36,39,42],"ul",{},[24,25,26],"li",{},"安装 / 启动失败",[24,28,29],{},"模型加载 / 兼容问题",[24,31,32],{},"工作流执行报错",[24,34,35],{},"生成画质问题",[24,37,38],{},"性能 / 显存限制",[24,40,41],{},"部署（SSG/托管）问题",[24,43,44],{},"插件 / 扩展冲突",[46,47],"hr",{},[49,50,52],"h2",{"id":51},"快速排查清单5-分钟快速修复","快速排查清单（5 分钟快速修复）",[14,54,55],{},"在进入详细解决方案前，先试试这些快速检查——能解决 80% 的常见问题：",[57,58,59,66,82,92,98],"ol",{},[24,60,61,65],{},[62,63,64],"strong",{},"重启 ComfyUI","（很多修改必须重启才会生效）。",[24,67,68,69,72,73,77,78,81],{},"确认模型文件放在",[62,70,71],{},"正确目录","（例如 LoRA → ",[74,75,76],"code",{},"models/lora/","，大模型 → ",[74,79,80],{},"models/checkpoints/","）。",[24,83,84,87,88,91],{},[62,85,86],{},"更新 ComfyUI"," 到最新版（在 ComfyUI 文件夹执行 ",[74,89,90],{},"git pull"," 或使用管理器更新）。",[24,93,94,97],{},[62,95,96],{},"释放显存","：关闭其他占用显卡的软件（游戏、剪辑软件），或降低图片分辨率。",[24,99,100,101,104,105,104,108,111],{},"检查节点连线：确保所有必需输入（如 ",[74,102,103],{},"model","、",[74,106,107],{},"conditioning",[74,109,110],{},"image","）都已正确连接。",[46,113],{},[49,115,117],{"id":116},"_1-安装与启动问题","1. 安装与启动问题",[119,120,122],"h3",{"id":121},"问题-1comfyui-无法启动无窗口-命令行闪退","问题 1：ComfyUI 无法启动（无窗口 / 命令行闪退）",[14,124,125,128,129,132,133,136],{},[62,126,127],{},"现象","：双击 ",[74,130,131],{},"run_nvidia_gpu.bat","（Windows）或 ",[74,134,135],{},"run.sh","（macOS/Linux）没反应，或终端立刻关闭。",[14,138,139,142],{},[62,140,141],{},"原因","：",[21,144,145,148,151],{},[24,146,147],{},"缺少 Python 3.10+（ComfyUI 要求 Python 3.10–3.11；3.12 及以上不支持）。",[24,149,150],{},"显卡驱动过时（NVIDIA/AMD 驱动与 PyTorch 不兼容）。",[24,152,153],{},"依赖损坏（Python 包缺失或异常）。",[14,155,156,142],{},[62,157,158],{},"解决方法",[57,160,161,168,179],{},[24,162,163,164,167],{},"安装 Python 3.10.11（推荐），安装时勾选 ",[62,165,166],{},"Add Python to PATH","。",[24,169,170,171],{},"更新显卡驱动：\n",[21,172,173,176],{},[24,174,175],{},"NVIDIA：用 GeForce Experience 或官网驱动工具",[24,177,178],{},"AMD：用 Radeon Software",[24,180,181,182],{},"修复依赖：\n",[183,184,189],"pre",{"className":185,"code":186,"language":187,"meta":188,"style":188},"language-bash shiki shiki-themes github-light github-dark","cd 你的ComfyUI目录\npip install --upgrade -r requirements.txt\n","bash","",[74,190,191,204],{"__ignoreMap":188},[192,193,196,200],"span",{"class":194,"line":195},"line",1,[192,197,199],{"class":198},"sj4cs","cd",[192,201,203],{"class":202},"sZZnC"," 你的ComfyUI目录\n",[192,205,207,211,214,217,220],{"class":194,"line":206},2,[192,208,210],{"class":209},"sScJk","pip",[192,212,213],{"class":202}," install",[192,215,216],{"class":198}," --upgrade",[192,218,219],{"class":198}," -r",[192,221,222],{"class":202}," requirements.txt\n",[46,224],{},[119,226,228],{"id":227},"问题-2启动时cuda-out-of-memory非生成时","问题 2：启动时“CUDA Out of Memory”（非生成时）",[14,230,231,233],{},[62,232,127],{},"：还没加载工作流，一启动就报显存不足。",[14,235,236,142],{},[62,237,141],{},[21,239,240,243],{},[24,241,242],{},"后台运行了多个 ComfyUI 实例。",[24,244,245],{},"其他软件占用了大量显存（如 Discord 硬件加速、Chrome 显卡任务）。",[14,247,248,142],{},[62,249,158],{},[57,251,252,255],{},[24,253,254],{},"关闭所有占用 GPU 的后台程序。",[24,256,257,258,261,262],{},"以",[62,259,260],{},"低显存模式","启动：\n",[21,263,264,272],{},[24,265,266,267,269,270],{},"编辑 ",[74,268,131],{}," 或 ",[74,271,135],{},[24,273,274,275,278,279],{},"在启动命令添加 ",[74,276,277],{},"--lowvram","：\n",[183,280,282],{"className":185,"code":281,"language":187,"meta":188,"style":188},"python main.py --lowvram\n",[74,283,284],{"__ignoreMap":188},[192,285,286,289,292],{"class":194,"line":195},[192,287,288],{"class":209},"python",[192,290,291],{"class":202}," main.py",[192,293,294],{"class":198}," --lowvram\n",[46,296],{},[119,298,300],{"id":299},"问题-3提示download-fp8-version-of-z-image-turbo","问题 3：提示“download fp8-version of z-image-turbo”",[14,302,303,142],{},[62,304,158],{},[57,306,307,310],{},[24,308,309],{},"下载 FP8 版本的 z-image-turbo 模型。",[24,311,312,313,316],{},"放入：",[74,314,315],{},"models/diffusion_models"," 文件夹。",[46,318],{},[49,320,322],{"id":321},"_2-模型加载与兼容问题","2. 模型加载与兼容问题",[119,324,326],{"id":325},"问题-1模型在-comfyui-中不显示","问题 1：模型在 ComfyUI 中不显示",[14,328,329,331],{},[62,330,127],{},"：下载的模型在节点下拉框里找不到。",[14,333,334,142],{},[62,335,141],{},[21,337,338,341,344],{},[24,339,340],{},"放错文件夹。",[24,342,343],{},"文件格式不支持 / 损坏。",[24,345,346],{},"没重启 ComfyUI，未扫描新模型。",[14,348,349,142],{},[62,350,351],{},"正确文件夹对照",[353,354,355,371],"table",{},[356,357,358],"thead",{},[359,360,361,365,368],"tr",{},[362,363,364],"th",{},"模型类型",[362,366,367],{},"正确文件夹",[362,369,370],{},"支持格式",[372,373,374,393,408,425,443],"tbody",{},[359,375,376,380,384],{},[377,378,379],"td",{},"大模型 Checkpoint",[377,381,382],{},[74,383,80],{},[377,385,386,389,390],{},[74,387,388],{},".ckpt"," ",[74,391,392],{},".safetensors",[359,394,395,398,402],{},[377,396,397],{},"LoRA",[377,399,400],{},[74,401,76],{},[377,403,404,389,406],{},[74,405,388],{},[74,407,392],{},[359,409,410,413,418],{},[377,411,412],{},"ControlNet",[377,414,415],{},[74,416,417],{},"models/controlnet/",[377,419,420,389,423],{},[74,421,422],{},".pth",[74,424,392],{},[359,426,427,430,435],{},[377,428,429],{},"Embedding",[377,431,432],{},[74,433,434],{},"models/embeddings/",[377,436,437,389,440],{},[74,438,439],{},".bin",[74,441,442],{},".pt",[359,444,445,448,453],{},[377,446,447],{},"VAE",[377,449,450],{},[74,451,452],{},"models/vae/",[377,454,455,389,457],{},[74,456,388],{},[74,458,392],{},[14,460,461,464],{},[62,462,463],{},"解决","：放对位置 → 重启 ComfyUI。",[46,466],{},[119,468,470],{"id":469},"问题-2model-load-failed模型加载失败","问题 2：“Model Load Failed”模型加载失败",[14,472,473,142],{},[62,474,141],{},[21,476,477,480,483],{},[24,478,479],{},"下载损坏（网络中断导致文件不完整）。",[24,481,482],{},"模型不兼容（如 SDXL 模型用在 SD1.5 工作流）。",[24,484,485],{},"量化模型（GGUF/INT4）缺少依赖。",[14,487,488,142],{},[62,489,463],{},[57,491,492,495,498],{},[24,493,494],{},"重新下载，核对文件大小。",[24,496,497],{},"确认模型版本匹配。",[24,499,500,501],{},"GGUF 模型需安装依赖：\n",[183,502,504],{"className":185,"code":503,"language":187,"meta":188,"style":188},"pip install llama-cpp-python accelerate\n",[74,505,506],{"__ignoreMap":188},[192,507,508,510,512,515],{"class":194,"line":195},[192,509,210],{"class":209},[192,511,213],{"class":202},[192,513,514],{"class":202}," llama-cpp-python",[192,516,517],{"class":202}," accelerate\n",[46,519],{},[119,521,523],{"id":522},"问题-3lora-controlnet-完全没效果","问题 3：LoRA / ControlNet 完全没效果",[14,525,526,142],{},[62,527,141],{},[21,529,530,533,536],{},[24,531,532],{},"缺少触发词。",[24,534,535],{},"节点接错。",[24,537,538],{},"强度（strength）设为 0。",[14,540,541,142],{},[62,542,463],{},[57,544,545,548,559],{},[24,546,547],{},"添加触发词。",[24,549,550,551],{},"正确连线：\n",[21,552,553,556],{},[24,554,555],{},"LoRA 模型输出 → KSampler 模型输入",[24,557,558],{},"ControlNet 输出 → KSampler control_net 输入",[24,560,561],{},"强度调到 0.5–1.0。",[46,563],{},[49,565,567],{"id":566},"_3-工作流执行错误","3. 工作流执行错误",[119,569,571],{"id":570},"问题-1missing-input缺失输入","问题 1：“Missing Input”缺失输入",[14,573,574,142,576,579,580,269,582,167],{},[62,575,127],{},[74,577,578],{},"KSampler"," 提示缺少 ",[74,581,103],{},[74,583,107],{},[14,585,586,142],{},[62,587,463],{},[57,589,590,597],{},[24,591,592,593,596],{},"使用顶部 ",[62,594,595],{},"Validate"," 检查错误。",[24,598,599],{},"重新正确连接核心节点。",[46,601],{},[119,603,605],{"id":604},"问题-2工作流在运行但不出图","问题 2：工作流在运行但不出图",[14,607,608,142],{},[62,609,141],{},[21,611,612,618,621],{},[24,613,614,617],{},[74,615,616],{},"Save Image"," 未连接或路径错误。",[24,619,620],{},"正面提示词为空。",[24,622,623],{},"KSampler steps 设为 0。",[14,625,626,142],{},[62,627,463],{},[57,629,630,633,636],{},[24,631,632],{},"确认保存节点连接正常、路径正确。",[24,634,635],{},"填写简单提示词测试。",[24,637,638],{},"步数设为 20–50。",[46,640],{},[119,642,644],{"id":643},"问题-3type-error类型不匹配","问题 3：“Type Error”类型不匹配",[14,646,647,142],{},[62,648,141],{},[21,650,651,654],{},[24,652,653],{},"把不兼容的端口连在一起（如 ControlNet 连到 model 输入）。",[24,655,656],{},"旧节点用在新模型（SD1.5 节点用于 SDXL）。",[14,658,659,142],{},[62,660,463],{},[21,662,663,666],{},[24,664,665],{},"输入输出类型必须匹配。",[24,667,668],{},"SDXL / FLUX 要用专用节点。",[46,670],{},[49,672,674],{"id":673},"_4-图像生成质量问题","4. 图像生成质量问题",[119,676,678],{"id":677},"问题-1生成纯黑-空白图","问题 1：生成纯黑 / 空白图",[14,680,681,142],{},[62,682,141],{},[21,684,685,688,691],{},[24,686,687],{},"提示词为空。",[24,689,690],{},"负面提示词过于严格。",[24,692,693],{},"模型损坏。",[14,695,696,142],{},[62,697,463],{},[57,699,700,703,706],{},[24,701,702],{},"使用简单提示词测试。",[24,704,705],{},"简化负面提示词。",[24,707,708],{},"更换正常模型。",[46,710],{},[119,712,714],{"id":713},"问题-2画面模糊画质差","问题 2：画面模糊、画质差",[14,716,717,142],{},[62,718,141],{},[21,720,721,724,727],{},[24,722,723],{},"分辨率太低。",[24,725,726],{},"步数太少。",[24,728,729],{},"模型不适合写实 / 精细场景。",[14,731,732,142],{},[62,733,463],{},[57,735,736,739,742],{},[24,737,738],{},"提高分辨率到 1024×1024 及以上。",[24,740,741],{},"步数设为 30–50。",[24,743,744],{},"使用高质量采样器：DPM++ 2M Karras。",[46,746],{},[119,748,750],{"id":749},"问题-3ai-不听提示词","问题 3：AI 不听提示词",[14,752,753,142],{},[62,754,141],{},[21,756,757,760,763],{},[24,758,759],{},"提示词太模糊。",[24,761,762],{},"关键词权重过高。",[24,764,765],{},"模型本身偏向性强。",[14,767,768,142],{},[62,769,463],{},[57,771,772,775,781],{},[24,773,774],{},"写具体、清晰的提示词。",[24,776,777,778,167],{},"合理使用权重 ",[74,779,780],{},"(词:1.2)",[24,782,783],{},"优先使用 SDXL 模型，服从度更高。",[46,785],{},[49,787,789],{"id":788},"_5-性能与资源问题","5. 性能与资源问题",[119,791,793],{"id":792},"问题-1out-of-memory显存不足","问题 1：“Out of Memory”显存不足",[14,795,796,142],{},[62,797,463],{},[57,799,800,803,806],{},[24,801,802],{},"降低分辨率。",[24,804,805],{},"开启模型卸载（Model Offloading）。",[24,807,808],{},"使用 INT4 / FP8 量化模型。",[46,810],{},[119,812,814],{"id":813},"问题-2生成速度极慢","问题 2：生成速度极慢",[14,816,817,142],{},[62,818,141],{},[21,820,821,824,827],{},[24,822,823],{},"在用 CPU 跑，没调用 GPU。",[24,825,826],{},"驱动 / PyTorch 异常。",[24,828,829],{},"步数/分辨率过高。",[14,831,832,142],{},[62,833,463],{},[57,835,836,839,842],{},[24,837,838],{},"确认终端显示“Using NVIDIA GPU”。",[24,840,841],{},"重装 GPU 版 PyTorch。",[24,843,844],{},"使用快速采样器，降低步数。",[46,846],{},[49,848,850],{"id":849},"_6-插件扩展相关崩溃","6. 插件/扩展相关崩溃",[14,852,853,855],{},[62,854,127],{},"：装了某个节点后 ComfyUI 闪退。",[14,857,858,142],{},[62,859,463],{},[57,861,862,869,872],{},[24,863,864,865,868],{},"删除 ",[74,866,867],{},"custom_nodes/"," 里对应插件文件夹。",[24,870,871],{},"安装插件所需依赖。",[24,873,874],{},"尽量用管理器安装兼容插件。",[46,876],{},[49,878,880],{"id":879},"_7-文字生成模糊-不正确","7. 文字生成模糊 / 不正确",[14,882,883,885],{},[62,884,141],{},"：常规扩散模型本身不擅长精确定位文字。",[14,887,888,142],{},[62,889,463],{},[57,891,892,895,898],{},[24,893,894],{},"使用支持文字的模型（FLUX.1 Kontext 等）。",[24,896,897],{},"只用简短大写单词。",[24,899,900],{},"后期在 PS 里加文字。",[46,902],{},[49,904,905],{"id":905},"避免问题的最佳实践",[57,907,908,911,914,917,920],{},[24,909,910],{},"模型文件夹分类整理。",[24,912,913],{},"保存可用的工作流备份。",[24,915,916],{},"新模型先简单测试再用于复杂流程。",[24,918,919],{},"定期更新 ComfyUI 和节点。",[24,921,922],{},"时刻关注显存占用。",[924,925,926],"style",{},"html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":188,"searchDepth":206,"depth":206,"links":928},[929,930,936,941,946,951,955,956,957],{"id":51,"depth":206,"text":52},{"id":116,"depth":206,"text":117,"children":931},[932,934,935],{"id":121,"depth":933,"text":122},3,{"id":227,"depth":933,"text":228},{"id":299,"depth":933,"text":300},{"id":321,"depth":206,"text":322,"children":937},[938,939,940],{"id":325,"depth":933,"text":326},{"id":469,"depth":933,"text":470},{"id":522,"depth":933,"text":523},{"id":566,"depth":206,"text":567,"children":942},[943,944,945],{"id":570,"depth":933,"text":571},{"id":604,"depth":933,"text":605},{"id":643,"depth":933,"text":644},{"id":673,"depth":206,"text":674,"children":947},[948,949,950],{"id":677,"depth":933,"text":678},{"id":713,"depth":933,"text":714},{"id":749,"depth":933,"text":750},{"id":788,"depth":206,"text":789,"children":952},[953,954],{"id":792,"depth":933,"text":793},{"id":813,"depth":933,"text":814},{"id":849,"depth":206,"text":850},{"id":879,"depth":206,"text":880},{"id":905,"depth":206,"text":905},"md",{},true,"/zh/basic-tutorial/trouble-shooting",{"title":5,"description":16},"zh/basic-tutorial/trouble-shooting","WPahkkhs87BvMyC1TnGICW3S2w02uAn4hQH9KA3qtm4",1773986044745]