Windows 11下ComfyUI-3D-Pack安装与CUDA环境配置指南

1. ComfyUI-3D-Pack Windows 11 安装完全指南

如果你正在Windows 11上尝试安装ComfyUI-3D-Pack这个强大的3D生成插件，但被复杂的安装过程困扰，这篇文章就是为你准备的。作为一个在Windows环境下折腾过无数次AI工具的老手，我将带你一步步完成这个看似复杂但完全可行的安装过程。

ComfyUI-3D-Pack是目前功能最全面的ComfyUI 3D生成插件之一，它集成了Hunyuan3D-2.1、TRELLIS、StableFast3D等多个前沿3D生成模型。但它的安装过程确实不简单——官方文档只有两行命令，而实际上这两行命令背后隐藏着大量需要手动处理的问题。

1.1 环境准备：打好基础才能事半功倍

在开始安装之前，我们需要确保系统环境满足基本要求。以下是我的实测环境配置：

为什么需要多版本CUDA？这是很多新手会困惑的地方。本插件的依赖库在Windows下需要从源码编译，不同的库对CUDA版本的检查严格程度不同：

• pytorch3d、diff-gaussian-rasterization、simple-knn：版本检查较宽松，可以用系统最新CUDA（13.1）编译
• torch-cluster、torch-scatter（rusty1s系列）：有严格的运行时CUDA版本检查，必须用与PyTorch cu126匹配的CUDA 12.8编译

因此，强烈建议在系统上保留多套CUDA Toolkit，按需切换，而不是只安装最新版本就清理了旧版本。

1.2 开发环境配置：VS2022是关键

所有编译操作必须在VS2022 Developer PowerShell中进行。这是我的标准配置命令：

powershell复制Import-Module "D:\Program Files\Microsoft Visual Studio\2022\Professional\Common7\Tools\Microsoft.VisualStudio.DevShell.dll"
Enter-VsDevShell -VsInstallPath "D:\Program Files\Microsoft Visual Studio\2022\Professional" -SkipAutomaticLocation -DevCmdArguments "-arch=x64"

如果你使用PyCharm作为开发环境，我强烈建议配置x64 Native Tools Command Prompt for VS 2022作为默认终端。这样可以避免"假激活"和环境嵌套问题，确保编译环境的一致性。

2. 官方安装步骤与关键修改

官方文档给出的安装命令看似简单：

bash复制# 官方命令（不可直接使用，需先修改配置）
python.exe -s -m pip install -r requirements.txt
python.exe install.py

但在Windows下直接执行这两行命令几乎肯定会失败。我们需要进行一些关键修改。

2.1 修改build_config.yaml：避免环境破坏

install.py脚本运行时会读取以下配置文件，其中硬编码了torch和CUDA版本：

code复制H:\PythonProjects3\Win_ComfyUI\custom_nodes\ComfyUI-3D-Pack\_Pre_Builds\_Build_Scripts\build_config.yaml

如果不修改这个文件，install.py会尝试按配置中的版本安装/降级torch和CUDA，极有可能破坏现有环境！

打开该文件，将其中的torch版本、CUDA版本等改为与你的实际环境一致：

yaml复制# 修改前（示例）
torch_version: "2.x.x"
cuda_version: "12.x"

# 修改后（与你的环境匹配）
torch_version: "2.7.1"
cuda_version: "12.6"

同时检查dependencies.txt中列出的六大CUDA扩展依赖。这个文件列出了需要从源码编译的库，在Windows下这些库无法通过install.py自动编译成功，必须手动处理。

2.2 安全执行依赖安装

为了避免破坏现有环境，我们需要使用--no-deps参数：

bash复制# 使用 --no-deps 避免踩坏环境中其他依赖的版本
python.exe -s -m pip install -r requirements.txt --no-deps

# 执行install.py时也可以添加--no-deps
python.exe install.py --no-deps

为什么要加--no-deps？因为requirements.txt中有些包的依赖关系会与现有环境冲突（例如scipy版本），加--no-deps只安装列出的包本身，不递归安装其依赖，避免依赖解析导致的版本降级。

注意：install.py会尝试从dependencies.txt中构建安装六大CUDA扩展。在Windows下这一步通常会失败，这是预期行为——失败的部分需要手动处理。

3. 六大核心CUDA依赖的手动安装

dependencies.txt中列出的六个库在Windows下必须手动处理。以下是各库的安装方式总览：

3.1 快速安装可直接pip的部分

对于可以直接通过pip安装的依赖，建议使用以下命令：

bash复制# spconv（选择与PyTorch CUDA版本匹配的包）
pip install spconv-cu120

# torch-scatter（预编译wheel，自动匹配版本）
pip install torch-scatter

# kiuikit（从git安装最新版）
pip install git+https://github.com/ashawkey/kiuikit.git

3.2 需要源码编译的依赖

对于nvdiffrast、diff-gaussian-rasterization、pytorch3d这些需要源码编译的库，我们需要设置正确的编译环境变量：

powershell复制$env:DISTUTILS_USE_SDK = "1"
$env:MSSdk = "1"
$env:FORCE_CUDA = "1"
$env:CUDA_HOME = "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v13.1"
$env:TORCH_CUDA_ARCH_LIST = "8.6"  # RTX 3090，按实际GPU修改

每个库的编译都有其特定的坑点，这里简要说明：

nvdiffrast：

• 需要修改setup.py以适配Windows
• 确保CUDA 13.1环境变量设置正确
• 可能需要手动指定ninja路径

diff-gaussian-rasterization：

• 需要GLM头文件
• 需要应用特定的patch解决Windows兼容性问题
• 编译过程中可能会遇到C++标准问题

pytorch3d：

• 需要移除pulsar相关代码
• 需要修改ext.cpp文件
• 编译时间较长，可能需要多次尝试

3.3 验证六大核心依赖

安装完成后，使用以下命令验证六大核心依赖是否就绪：

python复制python -c "
import diff_gaussian_rasterization; print('✅ diff_gaussian_rasterization')
import nvdiffrast;    print('✅ nvdiffrast   ', nvdiffrast.__version__)
import kiui;          print('✅ kiuikit       (no __version__)')
import pytorch3d;     print('✅ pytorch3d    ', pytorch3d.__version__)
import torch_scatter; print('✅ torch_scatter', torch_scatter.__version__)
import spconv;        print('✅ spconv       ', spconv.__version__)
print('🎉 六大核心依赖全部就绪！')
"

4. 补充依赖：运行时才暴露的隐式依赖

即使六大核心依赖全部安装完成，ComfyUI-3D-Pack在首次启动时仍会因为隐式依赖缺失而报ModuleNotFoundError。这些包在requirements.txt中没有列出，需要逐一补装。

4.1 可直接pip安装的隐式依赖

bash复制# 一次性安装所有可直接安装的补充依赖
pip install scs texttable "optimum[quanto]" meshio pyamg torch-scatter plotly

# 替换onnxruntime CPU版为GPU版
$env:TEMP = "H:\PythonProjects3\Win_ComfyUI\temp"
$env:TMP  = "H:\PythonProjects3\Win_ComfyUI\temp"
New-Item -ItemType Directory -Force -Path "H:\PythonProjects3\Win_ComfyUI\temp"
pip uninstall onnxruntime onnxruntime-gpu -y
pip install onnxruntime-gpu

4.2 需要源码编译的补充依赖

simple-knn（PyPI上有同名假包，必须从源码编译）：

bash复制pip uninstall simple-knn -y
git clone https://github.com/camenduru/simple-knn.git
cd simple-knn
$env:FORCE_CUDA = "1"; $env:TORCH_CUDA_ARCH_LIST = "8.6"
$env:CUDA_HOME = "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v13.1"
python setup.py bdist_wheel
pip install dist\simple_knn-1.0.0-cp312-cp312-win_amd64.whl
cd ..

torch-cluster（严格CUDA版本检查，必须用CUDA 12.8编译）：

powershell复制$env:CUDA_HOME = "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8"
$env:PATH = "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\bin;" + $env:PATH
$env:DISTUTILS_USE_SDK = "1"; $env:MSSdk = "1"
$env:FORCE_CUDA = "1"; $env:TORCH_CUDA_ARCH_LIST = "8.6"
pip install torch-cluster --no-build-isolation

4.3 各隐式依赖的来源

5. 验证安装与问题排查

5.1 验证所有依赖

安装完成后，使用以下命令验证所有依赖：

python复制python -c "
import diff_gaussian_rasterization; print('✅ diff_gaussian_rasterization')
import nvdiffrast;    print('✅ nvdiffrast   ', nvdiffrast.__version__)
import kiui;          print('✅ kiuikit       (no __version__)')
import pytorch3d;     print('✅ pytorch3d    ', pytorch3d.__version__)
import torch_scatter; print('✅ torch_scatter', torch_scatter.__version__)
import spconv;        print('✅ spconv       ', spconv.__version__)
import plotly;        print('✅ plotly          ', plotly.__version__)
import scs;           print('✅ scs             ', scs.__version__)
import texttable;     print('✅ texttable        ', texttable.__version__)
from optimum.quanto import QModuleMixin
print('✅ optimum.quanto   可用')
import meshio;        print('✅ meshio           ', meshio.__version__)
import pyamg;         print('✅ pyamg            ', pyamg.__version__)
import simple_knn;    print('✅ simple_knn        (no __version__)')
import onnxruntime as ort
print('✅ onnxruntime      ', ort.__version__)
print('   providers:', ort.get_available_providers())
import torch_cluster; print('✅ torch_cluster    ', torch_cluster.__version__)
print()
print('🎉 所有依赖安装完成！')
"

5.2 验证ComfyUI-3D-Pack加载

启动ComfyUI，在日志中确认以下关键信息：

code复制[SPARSE] Backend: spconv, Attention: xformers        ← spconv + xformers正常
mmgp available for memory management                  ← 内存管理正常
Hunyuan3D-2.1 modules loaded successfully             ← 核心模块加载成功
torch_cluster available - using original FPS sampling ← torch_cluster正常
✅ providers: TensorrtExecutionProvider, CUDAExecutionProvider  ← GPU加速正常

5.3 已知的非致命警告

插件加载成功后，日志中可能会出现以下警告，这些都是可以忽略的：

6. 完整安装流程图与系列索引

6.1 安装流程图

code复制开始
 │
 ├─ Step 1：修改 build_config.yaml
 │          将 torch/cuda 版本改为与环境匹配
 │
 ├─ Step 2：第一次依赖安装
 │          pip install -r requirements.txt --no-deps
 │
 ├─ Step 3：第二次依赖安装
 │          python install.py --no-deps
 │          （六大 CUDA 扩展在 Windows 下会失败，属预期）
 │
 ├─ Step 4：手动安装六大核心 CUDA 依赖
 │   ├─ spconv          → pip install spconv-cu120
 │   ├─ torch-scatter   → pip install torch-scatter
 │   ├─ kiuikit         → pip install git+...
 │   ├─ nvdiffrast      → 源码编译（见博客）
 │   ├─ diff-gaussian   → 源码编译（见博客）
 │   └─ pytorch3d       → 源码编译（见博客）
 │
 ├─ Step 5：手动补充隐式依赖
 │   ├─ pip 直装：plotly, scs, texttable, optimum[quanto],
 │   │            meshio, pyamg, torch-scatter
 │   ├─ 替换：onnxruntime → onnxruntime-gpu
 │   ├─ 源码编译：simple-knn（camenduru 版，CUDA 13.1）
 │   └─ 源码编译：torch-cluster（CUDA 12.8，严格版本匹配）
 │
 ├─ Step 6：启动 ComfyUI 验证
 │          观察日志，确认无 ModuleNotFoundError
 │
 └─ 完成 ✅
    Hunyuan3D-2.1 modules loaded successfully

6.2 系列文章索引

对于每个具体组件的编译和安装问题，我撰写了详细的专题文章：

7. 个人经验与建议

经过多次安装和测试，我总结出以下几点经验：

1. 环境隔离至关重要：建议使用conda或venv创建独立环境，避免影响系统Python环境。我曾经因为在一个已有环境中尝试安装，导致原有项目无法运行。

2. 耐心是关键：整个安装过程可能需要4-6小时，特别是源码编译部分可能会遇到各种问题。保持耐心，一步步解决。

3. 日志是好朋友：遇到问题时，仔细阅读错误日志。90%的问题都能从日志中找到线索。

4. 版本匹配是核心：PyTorch、CUDA、Python版本必须严格匹配。一个小版本差异就可能导致编译失败或运行时错误。

5. 备份很重要：在重大操作前（如切换CUDA版本），备份当前环境或创建系统还原点。

6. 社区资源：遇到问题时，GitHub的issue页面和论坛��宝贵的资源。很多问题可能已经被其他人遇到并解决了。

最后，虽然安装过程复杂，但一旦成功，ComfyUI-3D-Pack提供的3D生成能力绝对值得这些努力。祝你好运！