Windows 11 下编译 diff-gaussian-rasterization 完整踩坑记录——PyTorch 2.7.1+cu126 × CUDA Toolkit 13.1 × RTX

# 克隆插件
cd Your_ComfyUI_Root\ComfyUI\custom_nodes\
git clone https://github.com/MrForExample/ComfyUI-3D-Pack.git
cd ComfyUI-3D-Pack

# 安装依赖
Your_ComfyUI_Root\python_embeded\python.exe -s -m pip install -r requirements.txt
Your_ComfyUI_Root\python_embeded\python.exe install.py

看起来很简单——但在 Windows 上，这条命令大概率会失败。

为什么在 Windows 上安装会失败？

requirements.txt 中包含大量需要从源码编译的 CUDA 扩展包，这些包：

没有预编译的 Windows wheel（作者主要在 Linux 下开发）
依赖特定版本的 CUDA Toolkit 和 MSVC 编译链
对 CUDA 版本匹配极为敏感，系统 CUDA 与 PyTorch 内置 CUDA 版本只要不一致就会报错

常见的安装失败包包括：

包	仓库	失败原因
`spconv`	https://github.com/traveller59/spconv	CUDA 版本不匹配，需指定版本
`diff-gaussian-rasterization`	https://github.com/ashawkey/diff-gaussian-rasterization	无预编译 wheel，需手动编译
`nvdiffrast`	https://github.com/NVlabs/nvdiffrast	MSVC 编译链配置问题
`kiuikit`	https://github.com/ashawkey/kiuikit	CUDA 扩展编译失败
`pytorch3d`	https://github.com/facebookresearch/pytorch3d	Windows 支持不完整
`pytorch_scatter`	https://github.com/rusty1s/pytorch_scatter	需匹配 PyTorch + CUDA 双版本

H:\PythonProjects3\Win_ComfyUI\custom_nodes\ComfyUI-3D-Pack\_Pre_Builds\_Build_Scripts\dependencies.txt

这些包几乎都需要手动从源码编译安装，每一个都可能遇到不同的坑。

本文解决的问题

本文聚焦其中一个：diff-gaussian-rasterization。

这个包是 3D Gaussian Splatting 的核心光栅化扩展，几乎所有 3DGS 相关工作流都依赖它。在以下环境组合下编译尤其容易出问题：

系统安装了较新的 CUDA Toolkit（本文为 13.1）
但 PyTorch 是基于旧版 CUDA 编译的（本文为 cu126 / CUDA 12.6）
Windows 上同时安装了多个版本的 Visual Studio（2022/2026 版 Community/Professional）

本文记录了在 Windows 11 + RTX 3090 + PyTorch 2.7.1+cu126 + CUDA Toolkit 13.1 环境下，从克隆仓库到 import 验证成功的完整过程，包含所有报错和对应解决方案。

📌 其余几个难装包（nvdiffrast、pytorch3d 等）的编译方法后续会陆续整理成文，欢迎关注。

nvdiffrast 本地环境定制编译安装：

Win11+RTX3090 亲测 · ComfyUI Hunyuan3D 全程实录 ②：nvdiffrast 源码编译实战（CUDA 13.1 零降级）

解决 Windows 下 NVIDIA nvdiffrast 编译失败：修改 setup.py + 环境配置全流程

一、环境信息

项目	版本 / 详情
操作系统	Windows 11 Professional Workstation (x64) Build 29531
GPU	NVIDIA GeForce RTX 3090 24GB
显卡驱动	595.02
nvidia-smi 显示 CUDA	13.0（驱动支持上限）
CUDA Toolkit（nvcc）	13.1（`V13.1.80 / compiler.36836380_0`，独立安装）
Python	3.12.11（venv 虚拟环境）
PyTorch	2.7.1+cu126（venv 虚拟环境）（内置编译 CUDA 12.6）
Visual Studio	2022 Professional v17.12.17（多版本共存）
终端环境	PyCharm 集成 pwsh7 + VS2022 编译链 + Clink v1.9.17
GLM 数学库	1.0.3（手动下载）

Release GLM 1.0.3 · g-truc/glm

💡 nvidia-smi 与 nvcc 版本不同是正常现象。 nvidia-smi 显示的是驱动支持的最高 CUDA Runtime 版本（13.0），nvcc --version 显示的是实际安装的 CUDA Toolkit 编译器版本（13.1），两者独立，不冲突。

【截图占位符 1】 nvidia-smi 完整输出截图（终端截图）

终端环境说明： 本文使用 PyCharm 集成的 pwsh7 + VS2022 编译链终端，启动时自动初始化 [vcvarsall.bat] Environment initialized for: 'x64'，可有效规避多版本 VS 共存导致的编译链冲突问题。

详见：

拒绝环境嵌套与"假激活"！PyCharm 终端终极调教：pwsh7 + VS2022编译链 + Clink 完美融合

二、背景与目的

diff-gaussian-rasterization 是 3D Gaussian Splatting 的核心 CUDA 扩展，ComfyUI 的多个节点依赖它。PyPI 上没有预编译的 Windows wheel，必须从源码自行编译。

核心难点： 本机 CUDA Toolkit 版本（13.1）与 PyTorch 编译时使用的 CUDA 版本（12.6）不一致，PyTorch 会在编译阶段强制拦截并报错。本文完整记录绕过此限制、最终成功编译的每一步操作。

三、前置条件

编译前请确认以下工具均已安装并可用：

# 逐条验证
git --version
python --version
nvcc --version
python -c "import torch; print(torch.__version__, torch.version.cuda)"

工具	本文版本	备注
Git	任意	—
CUDA Toolkit	13.1	nvcc 需在 PATH 中
Visual Studio 2022	Professional v17.12.17	需安装"使用 C++ 的桌面开发"工作负载
Python (venv)	3.12.11	虚拟环境需已激活
PyTorch	2.7.1+cu126	—

【截图占位符 2】 pip show torch 输出截图

⚠️ 多版本 VS 共存注意事项 本机同时安装了 VS 2019（社区版 + 专业版）和 VS 2022 Professional，多版本共存时 VC 编译链容易重复激活，导致后续 DISTUTILS_USE_SDK 相关报错。强烈建议使用集成了 VS2022 编译链的终端环境，参见上方链接。

四、Step 1 — 克隆仓库

推荐使用 ashawkey 的修复版（相比原版修复了若干 Windows 兼容性问题）：

https://github.com/ashawkey/diff-gaussian-rasterization

cd H:\PythonProjects3\Win_ComfyUI
git clone https://github.com/ashawkey/diff-gaussian-rasterization.git
cd diff-gaussian-rasterization

原版仓库：https://github.com/graphdeco-inria/diff-gaussian-rasterization

推荐修复版：https://github.com/ashawkey/diff-gaussian-rasterization

五、Step 2 — 准备 GLM 数学库

diff-gaussian-rasterization 的 CUDA 代码依赖 GLM（OpenGL Mathematics）头文件库，通过 git submodule 引入。

Windows 下 submodule 经常为空，需手动处理。

方法 A：git submodule 拉取（网络畅通时优先）

git submodule update --init --recursive
Test-Path "third_party\glm\glm\glm.hpp"
# 输出 True 则成功，可跳过方法 B

方法 B：手动下载后链接（推荐，稳定可靠）

1. 前往 GLM 1.0.3 Release 下载 glm-1.0.3.zip

2. 解压后将 glm 文件夹复制到 D 盘根目录（或其他位置），确保目录结构为：D:\glm\glm\glm.hpp（即 glm.hpp 在 glm\glm\ 层级下）

3. 创建符号链接或直接复制到仓库：

方式一：符号链接（省空间）

# 方式一：符号链接（省空间）
New-Item -ItemType Directory -Path "third_party\glm" -Force
New-Item -ItemType SymbolicLink -Path "third_party\glm\glm" -Target "D:\glm\glm"

方式二：直接复制（更稳妥）

# 方式二：直接复制（更稳妥）
New-Item -ItemType Directory -Path "third_party\glm" -Force
Copy-Item "D:\glm\glm" "third_party\glm\glm" -Recurse

4. 验证（必须为 True 才能继续）：

Test-Path "third_party\glm\glm\glm.hpp"

六、Step 3 — 绕过 CUDA 版本不匹配检查

问题说明

编译时 PyTorch 会强制校验 nvcc 版本与自身编译时的 CUDA 版本是否一致：

RuntimeError: The detected CUDA version (13.1) mismatches the version that was
used to compile PyTorch (12.6). Please make sure to use the same CUDA versions.

调用链为：

python -m build
  → setuptools build_ext
    → torch/utils/cpp_extension.py :: build_extensions()
      → _check_cuda_version()   ← 异常在此抛出

为什么不改 setup.py？

setup.py 本身不含任何版本检查逻辑，检查完全由 PyTorch 在 build_extensions() 阶段注入，必须修改 cpp_extension.py

操作步骤

如若不好操作，请把本文章链接发给适合的 AI 工具帮助解读！

① 备份原文件（务必先做！）

请替换为自己虚拟环境中的实际路径

$file = "H:\PythonProjects3\Win_ComfyUI\.venv\Lib\site-packages\torch\utils\cpp_extension.py"
Copy-Item $file "$file.bak"
Test-Path "$file.bak"
# 输出 True 表示备份成功

② 确认目标行缩进

(Get-Content $file)[476..481] | ForEach-Object -Begin {$i=477} -Process {"$i`: $_"; $i++}

正常输出：

478:         if cuda_ver.major != torch_cuda_version.major:
479:             raise RuntimeError(CUDA_MISMATCH_MESSAGE.format(...))
480:         warnings.warn(CUDA_MISMATCH_WARN.format(...))

③ 精确替换：raise → pass

(Get-Content $file) -replace '^            raise RuntimeError\(CUDA_MISMATCH_MESSAGE', '            pass  # raise RuntimeError(CUDA_MISMATCH_MESSAGE' | Set-Content $file

正则开头的 ^ 加 12 个空格精确匹配缩进，避免误替换其他行。

④ 验证替换结果

(Get-Content $file)[476..481] | ForEach-Object -Begin {$i=477} -Process {"$i`: $_"; $i++}

期望输出：

478:         if cuda_ver.major != torch_cuda_version.major:
479:             pass  # raise RuntimeError(CUDA_MISMATCH_MESSAGE...
480:         warnings.warn(CUDA_MISMATCH_WARN.format(...))

⚠️ 常见错误：若只注释 raise 而不加 pass，if 块变为空块，Python 解析时报： IndentationError: expected an indented block after 'if' statement 解决：还原备份后重新执行③，确保替换为 pass 而非注释。

⑤ 出错时还原

Copy-Item "$file.bak" $file -Force

📌 持久性说明：此修改直接编辑 PyTorch 库文件。重装或升级 PyTorch 后修改会被覆盖，需重新打补丁。CUDA 13.x 对 12.x API 向后兼容，运行时风险极低。

七、Step 4 — 设置编译环境变量并编译

关键环境变量说明

变量	值	作用
`DISTUTILS_USE_SDK`	`1`	告知 distutils 使用已激活的 SDK，避免 VC 环境重复激活报错
`MSSdk`	`1`	辅助确认 SDK 环境已就绪
`USE_NINJA`	`0`	禁用 Ninja，改用 MSBuild 直接编译，便于暴露真实错误信息

⚠️ 重要：必须在同一个 PowerShell 会话中连续执行以下所有命令。 python -m build 会启动子进程，子进程无法继承当前会话临时设置的 $env: 变量。关闭终端重开后需重新设置环境变量。

完整编译命令

# 进入仓库目录
cd H:\PythonProjects3\Win_ComfyUI\diff-gaussian-rasterization

# 设置环境变量
$env:DISTUTILS_USE_SDK = "1"
$env:MSSdk = "1"
$env:USE_NINJA = "0"

# 清理上次编译残留
Remove-Item -Path build, dist, *.egg-info -Recurse -Force -ErrorAction SilentlyContinue

# 开始编译（需要 5~15 分钟）
python -m build --wheel --no-isolation --verbose

编译过程中会看到 nvcc 逐文件编译输出：

[1/5] nvcc ... cuda_rasterizer/forward.cu ...
[2/5] nvcc ... cuda_rasterizer/backward.cu ...
...

编译成功标志

Successfully built diff_gaussian_rasterization-0.0.0-cp312-cp312-win_amd64.whl

wheel 文件保存于 dist\ 目录。

八、Step 5 — 安装 wheel

pip install dist\diff_gaussian_rasterization-0.0.0-cp312-cp312-win_amd64.whl --force-reinstall

输出：

Successfully installed diff-gaussian-rasterization-0.0.0

九、Step 6 — 验证安装

⚠️ 必须切换到仓库目录之外再验证！ 若在 diff-gaussian-rasterization\ 目录内运行，Python 会优先加载本地源码目录而非已安装的包，导致： ImportError: cannot import name '_C' from partially initialized module（循环导入）

cd H:\PythonProjects3\Win_ComfyUI
python -c "import diff_gaussian_rasterization; print('✅ 安装成功')"

输出 ✅ 安装成功 即完成全部流程。

十、踩坑全记录

#	错误信息摘要	根本原因	解决方案
1	`RuntimeError: CUDA version mismatch (13.1 vs 12.6)`	nvcc 与 PyTorch 编译 CUDA 版本不一致	修改 `cpp_extension.py`，`raise` 改为 `pass`
2	`IndentationError: expected an indented block`	注释 `raise` 后 `if` 块变为空块	使用 `pass` 占位，而非注释
3	`UserWarning: DISTUTILS_USE_SDK is not set`	多版本 VS 共存导致 VC 环境重复激活	设置 `$env:DISTUTILS_USE_SDK=1` 和 `$env:MSSdk=1`
4	`fatal error C1083: 'glm/glm.hpp': No such file or directory`	git submodule 未拉取，GLM 目录为空	手动下载 GLM 1.0.3 并链接/复制到 `third_party/glm/glm/`
5	`ninja: build stopped: subcommand failed`	Ninja 隐藏了真实错误	设置 `$env:USE_NINJA=0` 禁用 Ninja
6	`ImportError: circular import`	在仓库源码目录内运行验证命令	切换到其他目录再运行 import 验证

十一、一键重新编译脚本

保存为 build_dgr.ps1，升级 PyTorch 或需要重新编译时直接运行（需要修改成自己的路径）：

# build_dgr.ps1
# 用途：重新编译 diff-gaussian-rasterization wheel
# 前提：已在 VS2022 编译链终端中激活虚拟环境

$repoDir = "H:\PythonProjects3\Win_ComfyUI\diff-gaussian-rasterization"
$venvDir = "H:\PythonProjects3\Win_ComfyUI"
$file    = "$venvDir\.venv\Lib\site-packages\torch\utils\cpp_extension.py"

# 1. 检查并打补丁
$line479 = (Get-Content $file)[478]
if ($line479 -match "raise RuntimeError") {
    Write-Host "⚙️  打补丁：跳过 CUDA 版本检查..."
    (Get-Content $file) -replace '^            raise RuntimeError\(CUDA_MISMATCH_MESSAGE', '            pass  # raise RuntimeError(CUDA_MISMATCH_MESSAGE' | Set-Content $file
} else {
    Write-Host "✅ 补丁已存在，跳过"
}

# 2. 设置环境变量
$env:DISTUTILS_USE_SDK = "1"
$env:MSSdk             = "1"
$env:USE_NINJA         = "0"

# 3. 编译
Set-Location $repoDir
Remove-Item -Path build, dist, *.egg-info -Recurse -Force -ErrorAction SilentlyContinue
python -m build --wheel --no-isolation --verbose

# 4. 安装
$whl = Get-ChildItem "dist\*.whl" | Select-Object -First 1
if ($whl) {
    pip install $whl.FullName --force-reinstall
    Write-Host "✅ 安装完成：$($whl.Name)"
} else {
    Write-Host "❌ 未找到 wheel 文件，请检查编译输出"
}

十二、参考资源

ashawkey/diff-gaussian-rasterization（推荐，Windows 修复版）

graphdeco-inria/diff-gaussian-rasterization（原版）

GLM 1.0.3 Release

PyTorch 官方安装页

拒绝环境嵌套与"假激活"！PyCharm 终端终极调教：pwsh7 + VS2022编译链 + Clink 完美融合

如有问题欢迎评论区交流，转载请注明出处。

龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

想要微信AI助手，真没必要买Mac mini，我用N1就跑起来了

龙虾开发者社区

Codex 提示词库精简版

龙虾开发者社区

OpenClaw Windows部署教程，免虚拟机直接安装

第一，如果你用的是公司电脑或者学校电脑，可能有安全软件拦截某些操作，这种情况下建议联系IT管理员。"我当时愣了一下，心想都2026年了还有人这么问，但转念一想，之前确实很多AI工具只支持Linux，Windows用户被劝退是常态。所以今天专门写一篇，说清楚OpenClaw在Windows上是原生安装、直接跑的，不需要虚拟机，不需要Docker，甚至不需要WSL。先说结论：OpenClaw的Wind