上一次装 gsplat 失败的经历我记得很清楚报错窗口刷了一屏红色最后停在那句熟悉的 “error: command C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.x\bin\nvcc.exe failed with exit code 1” 上然后我开始怀疑人生。如果你也卡在 Windows 上装这个库别慌这条路我替你走通了。gsplat 是最近两年 3D 高斯泼溅3D Gaussian Splatting方向绕不开的库基于 CUDA 实现了可微的快速光栅化器PyTorch 生态里直接调用训练和渲染速度都很快。它支撑着 nerfstudio 里最常用的 splatfacto、以及各种自研 SLAM 和数字人项目。但这个库官方主要面向 Linux 开发Windows 属于“能跑但不保证”加上编译链复杂新手常常在环境阶段就被劝退。这篇文章就把我在 Windows 上从零部署 gsplat 的全过程拆开讲包括环境准备、依赖选型、编译安装、坑位排查、还有最终跑通训练和渲染验证的完整流程。我不扯虚的每一步都是实测下来的结果。无论你是刚接触 3D 高斯泼溅的新人还是被 Windows 环境搞到头大的老手照着这个流程走一遍大概率能少折腾两天。1. 部署前的准备先把“为什么这么难”搞清楚1.1 gsplat 到底是个什么东西它依赖什么gsplat 不是一个单纯的 Python 包它内部包含大量 CUDA 和 C 扩展安装过程本质上是在你机器上现场编译一堆针对 GPU 的算子。这意味着它需要完整的编译链而不是像纯 Python 包那样解压即用。它的核心依赖有这几层PyTorch提供张量运算和自动求导gsplat 的算子要嵌入 PyTorch 的扩展体系里。CUDA Toolkit提供 nvcc 编译器和 CUDA 运行时库编译 gsplat 的 CUDA 源码必须用。MSVCMicrosoft Visual C 编译器Windows 下编译 C 和 CUDA 混合代码的默认工具链cl.exe 和 nvcc 要配合工作。Ninja一个更快的构建工具PyTorch 扩展默认用 ninja 来并行编译Python 的 setuptools 在背后调用它。在 Linux 上这些基本是系统包管理器一条命令的事但在 Windows 上每个都要单独装而且版本必须对得上这就是麻烦的根源。还有一个隐性难点gsplat 的某些版本会针对显卡架构生成不同的 SASS 代码如果你的显卡太新工具链太旧或者编译时没指定好TORCH_CUDA_ARCH_LIST就会出现“编译成功但运行时卡死”或“找不到匹配的 kernel”这类折磨人的问题。1.2 为什么官方不直接给 Windows 轮子好问题。其实 PyPI 上是有 gsplat 的 wheel 包的你执行pip install gsplat通常能装上预编译的版本。但问题在于这个 wheel 不一定匹配你的 CUDA 版本和 PyTorch 版本组合而且某些功能比如和 nerfstudio 配合时的特定版本要求还是需要源码编译。我实测下来的结论是如果你的需求只是简单跑一下官方示例pip install gsplat就够了装完即用。但如果你要配合 nerfstudio 的 splatfacto、要改源码做二次开发、或者要跑最新版 main 分支上的新特性那就必须走源码编译这条路。而源码编译在 Windows 上的坑简直是一个接一个。这篇博文我会把两条路线都覆盖但重点放在源码编译上因为这才是真正考验人的部分。2. 基础环境搭建武装到牙齿的 Windows 开发机2.1 硬件要求先看看你显卡够不够格gsplat 本质是 GPU 密集型计算对显卡要求不低。先说结论NVIDIA 显卡必须AMD 和 Intel 核显可以直接放弃了。原因是 CUDA 是 NVIDIA 的私有技术gsplat 没有针对其他厂商的 GPU 做后端。具体建议分为三档显卡型号显存建议体验评价RTX 30 系列3060/3070/30808GB 以上完全够用训练小场景没问题RTX 40 系列4060/4070/4080/409012GB 以上最推荐Ampere/Ada 架构兼容性好旧款 GTX 16 系列、RTX 20 系列6GB 以上能跑但编译和训练都比较费劲显存直接决定你能否训练一个场景。3D 高斯泼溅训练时一个包含几百张图片的场景中间要保存大量梯度信息6GB 显存跑起来会频繁 OOM。哪怕是推理和查看器渲染模型加载也需要 2~4GB 显存。所以如果只是入门验证建议至少 8GB。2.2 CUDA Toolkit版本选择比你想的重要CUDA 是 gsplat 编译和运行的大前提。但注意一个问题Windows 系统上显卡驱动会自带一个 CUDA 运行时就是你在控制面板里看到那个NVIDIA Control Panel - 系统信息 - 组件里显示的版本这个版本是驱动级的不用你管。你需要安装的是CUDA Toolkit它提供 nvcc 编译器、cuBLAS、cuDNN 等开发库。安装哪个版本有讲究原则是以 PyTorch 支持的 CUDA 版本为基准。比如 PyTorch 2.x 官方支持 cu118、cu121、cu124那你就优先选这几个版本不要装最新的 CUDA 13.x 全家桶否则 torch 的预编译包和你的 CUDA 版本对不上会要命。我的建议是装CUDA 12.1 或 12.4这两个版本是当前生态最成熟的。下载地址是 NVIDIA 官网的 CUDA Toolkit Archive选择 Windows x86_64 版本因为 gsplat 目前不太可能在 ARM Windows 上顺利编译。安装时选“自定义”然后只勾选 “CUDA” 相关组件不要勾选 “Driver” 那项避免把现有的显卡驱动覆盖掉。那一步非常阴险如果选了可能直接让你的显卡驱动版本倒退导致 3D 程序全部报错。2.3 MSVC 编译链被很多人低估的关键一环在 Windows 上编译含 CUDA 代码的扩展光有 nvcc 不够还必须搭配 MSVC 的 cl.exe。而且cl.exe 的版本要和 nvcc 兼容否则编译时会出现奇奇怪怪的错误。安装方式很简单去微软官网下载 Visual Studio Build Tools注意不是完整的 Visual Studio IDE虽然 IDE 也可但 Build Tools 体积小不少安装时勾选使用 C 的桌面开发工作负载Windows 10/11 SDK选最新版本就行安装完后默认路径是C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools。这个路径后面会用到最好一开始就记住。有一点很多教程没提构建工具安装完成后最好先手动打开 “x64 Native Tools Command Prompt for VS 2022” 跑一次让它初始化一下环境变量确认 cl.exe 能正常调用。因为你后面所有编译操作本质上都需要这个环境。2.4 Python 与虚拟环境Miniconda 是最省心的方案Python 版本建议选 3.10 或 3.11PyTorch 和 gsplat 对这两个版本的支持最稳定。我不推荐直接用系统 Python因为后边装各种依赖包、冲突了很难清理。用 Miniconda 建独立环境就算搞坏了删掉重建就行成本极低。安装 Miniconda 后打开 Anaconda Prompt 或者任意终端先创建一个干净的虚拟环境conda create -n gsplat python3.10 conda activate gsplat这一步之后你的所有操作都在这个环境里进行。3. 核心部署全流程从空环境到跑通训练3.1 安装 PyTorch版本搭配是首要任务不要用pip install torch装默认版本因为默认装的可能是 CPU 版本或 CUDA 版本不匹配。正确做法是去 PyTorch 官网找到对应的安装命令。以 CUDA 12.1 为例pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121这里有个细节安装完成后一定要验证一下 torch 是否真的能调用 GPU。python -c import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.version.cuda)如果输出第一行是 2.x.xcu121第二行是 True说明 PyTorch 装对了。如果第二行是 False说明装成了 CPU 版本要找原因别急着装 gsplat。3.2 安装 gsplat 的两种方式pip 包和源码编译方式一pip 直接安装快速验证pip install gsplat装完后跑个最简单的验证import torch from gsplat import rasterization print(gsplat imported successfully)如果没报错说明预编译 wheel 和你的 torch/CUDA 环境匹配。这种方式适合只是浅尝辄止的场景。方式二源码编译推荐功能完整源码编译能拿到最新特性也能避免 wheel 和本地环境不匹配的问题。操作如下git clone https://github.com/nerfstudio-project/gsplat.git cd gsplat pip install -e .但先别急着执行源码编译前必须把三个环境变量准备好否则大概率中途报错。设置 CUDA_HOME 和 PATH$env:CUDA_HOME C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.4 $env:PATH ;C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.4\bin我强烈建议直接用 PowerShell 的$env:形式一次性在当前窗口设置别去改系统环境变量因为改错了影响面太大。设置 TORCH_CUDA_ARCH_LIST这一步非常关键它告诉编译器你的显卡架构。比如 RTX 30 系列是 Ampere 架构计算能力为 8.6RTX 40 系列是 Ada Lovelace计算能力为 8.9。设置方法$env:TORCH_CUDA_ARCH_LIST 8.6如果你是 40 系显卡就设成8.9如果是 30 系就设成8.6。一条命令解决问题别偷懒。不设的话编译器会尝试自动探测但在 Windows 上探测经常失败然后编译出一堆垃圾代码。确认 MSVC 环境源码编译需要 cl.exe 在 PATH 里。最简单的方式是直接用 “x64 Native Tools Command Prompt for VS 2022” 启动终端或者手动添加到 PATH$env:PATH ;C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.40.33807\bin\Hostx64\x64注意路径末尾版本号可能不一样去你的安装目录看一眼实际版本。设置好这三个之后再执行pip install -e .编译过程会持续几分钟期间屏幕会刷大量日志看到Creating library ... and object ...这类说明正在编译 C/CUDA 扩展。最终出现Successfully installed gsplat就说明大功告成。3.3 验证安装别急着跑大项目装完之后先做一个小验证确保 gsplat 的 CUDA 算子真的能工作而不是只 import 成功但一运行就崩。跑一下官方 benchmark 里的快速示例cd examples python benchmark.py --help如果输出正常说明至少模块能加载。更稳妥的做法是跑一小段完整的光栅化流水线import torch from gsplat import rasterization means torch.randn(1000, 3, devicecuda) scales torch.rand(1000, 3, devicecuda) quats torch.randn(1000, 4, devicecuda) opacities torch.sigmoid(torch.randn(1000, 1, devicecuda)) colors torch.randn(1000, 3, devicecuda) viewmats torch.eye(4, devicecuda).unsqueeze(0) Ks torch.tensor([[[1000.0, 0, 128], [0, 1000, 128], [0, 0, 1]]], devicecuda) width, height 256, 256 renders, alphas, meta rasterization( means, scales, quats, opacities, colors, viewmats, Ks, width, height ) print(renders.shape, alphas.shape)输出torch.Size([1, 256, 256, 3]) torch.Size([1, 256, 256, 1])就说明渲染管线通了。3.4 顺手把 nerfstudio 装上绝大多数人部署 gsplat 是为了配合 nerfstudio 里的 splatfacto 使用。这里有个版本搭配问题nerfstudio 对 gsplat 的版本要求比较严格老版本 nerfstudio 配新版本 gsplat 会直接报导入错误。我的建议是装 nerfstudio 最新的稳定版本然后让它的依赖解析器自动处理 gsplat 版本。pip install nerfstudio安装时它会自动重新安装一批依赖如果它把 gsplat 降级或升级了不要惊慌让它装完。这时候再看 gsplat 版本python -c import gsplat; print(gsplat.__version__)确保能正常输出版本号就行。4. 实操验证用真实数据走一遍训练流程4.1 先用内置数据集快速验证环境装好后别急着上自己的数据先用公开小数据集验证全流程能不能跑通。gsplat 的 examples 目录里有一个简单的脚本可以先生成一组随机相机位姿和图像直接开始训练。这一步的目的是确认训练循环本身没有环境问题避免后面拿真实数据排查问题时分不清是环境问题还是数据问题。我的做法是先跑一段时间观察 GPU 利用率。打开任务管理器切到“性能”标签看 GPU 的利用率是否稳定在 80% 以上。如果利用率极低说明可能又回到 CPU 模式了需立刻检查 torch.cuda.is_available()。4.2 用 nerfstudio 跑 splatfacto 训练自己的数据用 nerfstudio 训练自定义数据核心流程是三步数据转换、训练、查看。第一步准备图片数据。把你拍摄的图片放到一个目录下然后用 ns-process-data 做预处理ns-process-data images --data /path/to/images --output-dir /path/to/processed_data --sfm-tool colmap这一步会调用 COLMAP 做特征提取和稀疏重建生成的位姿文件是后续训练的基础。COLMAP 如果没装的话Windows 上要先去下载官方的 Windows 预编译包把COLMAP.bat所在目录加入 PATH。第二步开始训练ns-train splatfacto --data /path/to/processed_data --max-num-iterations 30000训练过程中终端会滚动打印 PSNR、SSIM 这些指标。30000 次迭代在 4090 上大概半小时到一小时3060 上可能要两小时。中途按CtrlC可以保存 checkpoint 并退出这个 checkpoint 可以直接用于之后的渲染。第三步启动查看器做可视化验证。如果你在本地训练默认会开一个 Web 查看器直接在浏览器里访问http://localhost:7007就能看到三维高斯点云的重建效果。我实际体验是splatfacto 在 Windows gsplat 源码编译版下运行很稳定渲染速度肉眼可见地快旋转视角时基本无延迟。唯一要注意的是训练过程中显存占用会逐步增长初期一个小场景可能要 6~8GB大场景直接 12GB 起显存不够就调小--max-num-iterations或者降低图片分辨率。4.3 训练完的效果怎么导出和复用训练完成后你会得到一个config.yml和*.ckpt文件。splatfacto 支持导出标准的 PLY 点云文件这个文件可以被其他 3D 软件或查看器直接使用ns-export gaussian-splat --load-config /path/to/config.yml --output-dir /path/to/exports导出之后你会得到一个 3D 高斯点云的 PLY里面每个点都带有位置、旋转四元数、尺度、不透明度、球谐系数等属性。拿这个文件可以在很多场景里复用比如游戏引擎、Web 3D 展示、或者进一步做视频合成。5. Windows 部署高频问题与排查手册5.1 问题速查表我把 Windows 部署 gsplat 时最容易踩的坑整理成一张表大家按症状对号入座比搜报错快得多。报错/症状根因解决方案MSVCP140.dll 缺失VS Build Tools 没装或未装 C 桌面开发组件重装 Build Tools确保勾选 C 工作负载nvcc : No such file or directoryCUDA Toolkit 的 bin 目录没加到 PATH在 PowerShell 里设置$env:PATH ;CUDA路径\\binninja: error: loading build.ninja编译过程中 ninja 崩溃或未安装pip install ninja后重试error: command cl.exe failedMSVC 编译环境未初始化用 x64 Native Tools 命令提示符启动终端或手动加 MSVC 路径CUBLAS_STATUS_ALLOC_FAILED显存不足降低 batch、降低图片分辨率换大显存显卡RuntimeError: No CUDA GPUs are availablePyTorch 装成 CPU 版本卸载后重新用--index-url指定 cu121/cu124 安装CUDA_HOME is not set or invalid环境变量没配好$env:CUDA_HOME C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v12.4Compiling with CUB相关奇怪的模板错误常见于 MSVC 和 CUDA 版本不兼容升级到 VS 2022 17.6配 CUDA 12.1问题基本消失训练中每秒迭代极慢可能用了 CPU 后端或 nvcc 编译出非优化代码检查 torch.version.cuda编译时设TORCH_CUDA_ARCH_LIST为你的显卡架构5.2 几个高频报错的详细复盘第一个必踩的坑ninja 未安装或版本过旧。源码编译时setuptools 默认调用 ninja 做并行构建。如果你没装 ninja或者 PATH 里没有 ninja.exe构建会直接死掉报错信息却不那么直白经常会是一坨乱糟糟的ninja: error: loading build.ninja。解决方案是先确保pip install ninja再把 ninja.exe 所在目录加入 PATH。这一步我建议做全局环境变量配置因为后面编译任何 PyTorch 扩展都会用到。第二个高频坑MSVC 环境没初始化。Windows 上最折腾的就是 cl.exe 找不到。我踩过几次坑之后发现最省事的方法是用 “x64 Native Tools Command Prompt for VS 2022” 启动终端在这个终端里执行 conda activate 和 pip install彻底避开手动配置环境变量的繁琐。因为那个快捷方式启动后已经把 INCLUDE、LIB、PATH 全部设置好了cl.exe、link.exe 都直接可用。但注意国内很多教程让你在 Anaconda Prompt 里编译那个环境默认不带 cl.exe除非你手动把 MSVC 路径塞进 PATH。第三个坑TORCH_CUDA_ARCH_LIST 没设导致编译产物异常。这个问题隐蔽性强。如果你不设置这个变量gsplat 编译时虽然能自动探测显卡但 Windows 下探测逻辑有时会出错生成的 cubin 文件可能不匹配你的显卡架构。症状表现为编译时没报错import 也成功但一运行就no kernel image is available或者直接 CUDA error。彻底解决方式就是开头设置好$env:TORCH_CUDA_ARCH_LIST 8.6 # 30系 $env:TORCH_CUDA_ARCH_LIST 8.9 # 40系 $env:TORCH_CUDA_ARCH_LIST 6.1 # 20系这个变量会让编译器只为特定架构生成代码大幅缩短编译时间也明显降低运行期出错的概率。第四个坑setuptools 版本过高导致 DistutilsError。在 Python 3.10、3.11 下新版 setuptools比如 70 版本有时候会和 PyTorch 的扩展编译机制冲突报error in gsplat setup command: use_2to3 is invalid之类的诡异错误。遇到这种直接把 setuptools 降级pip install setuptools68.0.0这个版本稳妥很多 PyTorch 扩展项目里都默认 pin 这个版本。5.3 部署完最值得做的几项检查安装不是终点能稳定运行才算数。建议按以下顺序做最终检查运行官方 benchmarkpython examples/simple_train.py --help确认训练脚本能正常加载数据。跑 100 步快速训练不要一上来就 30000 步先跑 100 步看看 loss 是否下降、是否有 NaN。查看 GPU 显存和利用率利用率和显存都是正常的说明 CUDA 算子真的在干活。尝试导出训练结束后执行ns-export gaussian-splat确认导出流程没问题。我之前遇到过一个奇葩现象训练正常、渲染正常、但导出时提示module gsplat has no attribute rasterize_gaussians。原因是电脑上有两个 gsplat 环境预编译 wheel 和源码版混用了。后来把环境理干净统一从源码编译版引入问题消失。所以装 gsplat最忌讳的就是 pip 和源码交替使用。6. 一些后续能玩的方向和个人经验gsplat 部署成功只是第一步。这个库的价值在于它把 3D 高斯泼溅的底层加速写到极致了你完全可以不依赖 nerfstudio直接用它的 Python API 构建自己的训练和渲染管线。我现在比较喜欢自己写一个简单的训练循环自定义数据和 loss跑起来比套 nerfstudio 更轻量调试也更直观。还有个实用建议如果你准备长期在 Windows 上做 3D 高斯相关开发建议把常用的环境变量写进一个 PowerShell profile 脚本里这样每次新开终端都能自动配好 CUDA_HOME、PATH、TORCH_CUDA_ARCH_LIST不用每次手工敲一遍。我个人是这样做的省心很多。再提一个时常被忽略的点磁盘空间。CUDA Toolkit、VS Build Tools、Miniconda 环境、训练数据、checkpoint加起来轻轻松松吃掉 30~50GB 空间。而且 PyTorch 扩展编译过程会产生大量临时文件建议给 gsplat 项目单独划分一个工作盘保持固态硬盘剩余空间充足。我之前是在只有 20GB 余量的系统盘上编译结果中途磁盘写满整个构建直接失败教训很深。最后如果你在部署时真的遇到我上面没有覆盖到的报错先把完整报错日志截下来然后从第一行开始看尤其是error前面的 warning很多时候真正的根因藏在 warning 里。Windows 部署本来就比 Linux 多一层地狱保持耐心一步步来跑通的那一刻你会觉得一切都值了。