在 ComfyUI 里跑 Hunyuan3D 2.x：两个阶段、封装节点包的选择与首次运行的报错排查

Hunyuan3D 2.x 不是单个模型，而是一对：一个负责提出几何形状的扩散 Transformer，以及一个把颜色投影到结果上的贴图阶段。ComfyUI 把两者都做成了节点，所以同一张原图，在一张图里能出来干净的剪影，在另一张图里可能只是一个没有贴图的空壳。

下面把两个阶段拆开讲：三种运行方式（ComfyUI 核心节点、Kijai 的封装节点包、托管接口）、各自的显存需求、真正影响结果的参数，以及首次运行时最常出现的报错究竟在说什么。

Hunyuan3D 的节点在做什么，以及对输入图片的要求

这条流程以图片为条件。只给一段文字提示词是驱动不了的，所以在 ComfyUI 里提示词必须先变成图片：要么在同一张图里接一段文生图流程，要么直接从硬盘加载文件。想清楚这一点，节点图的形状基本就定了：一个图像加载节点、一个把一张或几张视图编码成条件的节点、一次在空 latent 上的采样、一个把 latent 解码成体素网格的节点、一个从体素里提取表面的节点，最后是保存 GLB 的节点。贴图加载的是另一套权重，跑的是另一种扩散，所以单独成组。

第一阶段出几何，第二阶段上颜色

几何阶段是一个跑在紧凑形状表示上的扩散 Transformer。按固定步数采样之后，把结果解码成稠密的体素网格，再用 marching cubes 提取三角面。得到的是一个封闭的三角网格，没有 UV，也没有材质，用来检查剪影可以，别的就谈不上了。贴图阶段从多个角度渲染这个网格，用多视图扩散模型生成彼此一致的视图，再把这些视图烘焙回表面，得到基础色、粗糙度和金属度贴图。厂商把 Hunyuan3D 2.1 的输出描述为 PBR；2.0 的贴图更简单，通常还要在 Blender 或 Substance Painter 里补一遍粗糙度。

• 几何阶段输入：一张图，或最多四张视图（前、后、左、右），主体干净、背景简单效果最好。
• 几何阶段输出：没有 UV、没有材质的三角网格，面数通常高到必须减面。
• 贴图阶段输入：这个网格，加上同一批参考视图，而且网格必须已经在场景里。
• 贴图阶段输出：在贴图阶段自己生成的 UV 上烘焙出的基础色、粗糙度和金属度贴图。

第一次下载之前的显存、硬盘与驱动预算

硬盘要按和显存一样的方式算账：几何检查点是 GB 级别，放进 checkpoints 目录；几何 VAE 放进 vae 目录；贴图阶段还要再带一套自己的权重，两个精度版本都留着的话，轻松占掉几十 GB。除非已经配好额外的模型路径，否则尽量和 ComfyUI 放在同一块盘上。按社区的常见反馈，在 12 GB 以上的较新显卡上，几何阶段大致是几十秒的量级，而贴图阶段是分钟量级。

三条路线：核心节点、社区封装节点包，还是托管接口

如果你一直保持 ComfyUI 更新，建议从核心节点起步：除了权重不用装别的东西，节点图也跟着版本一起走。节点类名在版本之间并不稳定，所以按 Hunyuan3D 前缀在节点菜单里搜索。由 Kijai 维护的封装包比核心支持出现得更早，把两个阶段收在同一个包里，暴露的开关也更多；代价是那份依赖清单必须和你的 torch、xformers 或 SageAttention、onnxruntime 版本对齐，这也是导入类报错最常见的来源。托管接口则把驱动问题整个绕开。

一步一步搭出图生 3D 的节点图

1. 加载参考图，围绕主体裁成正方形：大约 1024 px，主体占满画面大部分。
2. 用 Hunyuan3D 的条件节点编码图片：单张图用单视图，最多四张用多视图，顺序保持一致。
3. 创建一个空的 Hunyuan3D latent。它是采样的起点，不是图像 latent，不要往里喂 VAE 编码过的图片。
4. 用 Hunyuan3D DiT 检查点采样：20 到 50 步，引导系数 5 到 8，采样器与调度器沿用官方示例图。
5. 把 latent 解码成体素，再转成网格。手指、绑带这类细结构就调高八叉树分辨率，显存吃紧就调低。
6. 存成 GLB 后到此为止，或把网格接进贴图那一组节点，它需要参考视图和另一套权重。

比采样器更影响网格的几个参数

和三个数字相比，采样器选哪个几乎不重要。八叉树分辨率决定表面是从多细的体素网格里提取出来的：256 是常见默认值，384 到 512 能保住细结构，三角面数也跟着成倍上涨，128 则是用圆掉的边缘换显存余量。引导系数决定模型有多听话：低于 5 左右，形状会往平均的团块上漂；高于 8 左右，它又会把噪点当成真实结构。步数遵循扩散模型的常见曲线，到 30 步左右提升明显，之后趋于平坦。换种子比动别的参数都值得先试：同一张图可能得到完全不同的拓扑，而不只是细节差异。

第一个小时里会撞上的报错

• 提 bug 之前先更新 ComfyUI：Hunyuan3D 的节点和它们的目录约定在版本之间改过。
• 看控制台，不要只盯浏览器标签页：解码和烘焙失败时，终端比界面先报出来。
• 先让几何阶段在单张图上跑通，再叠加贴图；剪影不行，贴图救不回来。
• 把能跑的节点图存成 JSON，节点包更新把它弄坏时可以快速回滚。

什么时候该用本地节点图，什么时候不该

需要可控性的时候，就在本地跑 Hunyuan3D 2.x：可以复现的固定种子、已经验证过的权重、没有按次计费，客户资产也不出本机。这份可控性的代价是驱动维护、显存上限，以及一个还要减面和展 UV 才能交付的网格。时间比可控性更重要时，托管生成器更合适：机器没有 CUDA 显卡、一下午要看五十个变体，或者同事正等着一个切片软件能直接打开的文件。不管走哪条路线，都要给后处理留出预算：网格都是三角面，八叉树调高时通常在几十万到上百万三角面之间，减面到 10% 到 30%、再在切片软件里做一次流形检查，都是日常步骤，而不是生成失败的证据。

常见问题

在 Open3DAI 中试一下

把同一份提示词或图片交给多个引擎，并排对比网格，然后导出 GLB、glTF、OBJ、STL、PLY 或 3MF。注册即赠免费积分，无需信用卡。