企业官网建设流程全解析

3D Gaussian Splatting这阵子的热度一直没下来，一句话概括：给你一个场景的一组照片，它能快速重建出一片支持实时渲染的三维高斯点云，训练完可以直接在那个窗口里自由旋转视角看效果。很多人被官方的渲染效果吸引，结果实际操作时卡在环境配置这一关。我自己前前后后在不同机器上配过七八次，Windows和Linux都折腾过，踩了不少坑。这篇东西就写给想快速跑通官方代码的读者，尽量把每一步讲清楚，包括为什么要这么配，以及那些文档里不会写的避坑点。

1. 配置前必须搞清楚的几件事

1.1 项目本质与运行链路

先说清楚这个项目跑起来到底需要什么。3D Gaussian Splatting官方仓库是graphdeco-inria/gaussian-splatting，核心思路是用一组多视角照片，先通过COLMAP做相机位姿估计，再用可微的高斯光栅化做优化渲染，最后得到一份可交互浏览的3D场景模型。

为什么环境配置容易把人整崩溃？因为它的依赖链条很长：需要CUDA Toolkit、PyTorch、COLMAP、submodule里的diff-gaussian-rasterization和simple-knn这两个扩展模块，Windows下还得配Visual Studio的MSVC编译器，Linux下对GCC版本也有要求。这中间任何一个环节版本不对，编译就挂。

我见过太多人卡在“diff-gaussian-rasterization找不到”或者“编译时报错MSVC版本不对”。所以配环境之前，一定要先理解你机器上要装哪些东西，版本之间怎么匹配，才能按顺序一步步来。

1.2 硬件和系统的底线要求

显卡必须支持CUDA，这点没有商量余地。NVIDIA的RTX系列、GTX 10系以上都行，但显存大小直接决定你能跑什么规模的数据。官方推荐24GB显存训练完整场景，实际用下来8GB跑小场景、低迭代数也能出结果，只是有些效果细节会妥协。

系统方面，Windows 10/11和Ubuntu 20.04/22.04是社区里用最多的。Windows下好处是驱动和CUDA的安装图形化操作直观，坏处是MSVC编译偶尔出莫名其妙的坑；Linux下编译相对顺利，但驱动安装对新手不太友好。我自己的倾向是：如果机器上已经装了COLMAP和CUDA相关的图形界面工具，用Windows；如果是新机器、纯服务器环境，Ubuntu更省心。

显存这块再强调一句：训练过程中的峰值显存大约是把静态场景分成高斯基元后逐帧光栅化需要的开销，场景越大、图像分辨率越高，显存占用越大。如果你只有8GB，建议把输入图片resize到1.6k以内，迭代次数降到15k，还是能看个大概效果的。

1.3 版本组合的“黄金套餐”

官方README其实给了推荐版本，但我实际测下来最稳的一套组合是这样的：

为什么Python不能太新？因为diff-gaussian-rasterization这个扩展模块是用C++写的，靠PyTorch的C++扩展机制编译，高版本Python环境里的ABI兼容性容易出问题。我自己在Python 3.10下编译通过过，但PyTorch版本、MSVC版本必须跟它匹配，一换就得重新试。

2. 工具链与依赖分析：为什么是它们

2.1 Anaconda和Miniconda该选谁

官方README建议用Miniconda，但我个人建议如果你机器上没有现成的Python环境管理工具，直接装Anaconda也挺好，因为它自带了conda、Python、常用科学计算包，新手省事。但如果你已经在用系统Python或者公司有统一环境规范，Miniconda更轻量。

核心原因是conda能创建隔离的虚拟环境。3DGS的依赖比较“娇气”，跟其他深度学习项目的包很容易冲突。比如你之前装过PyTorch 1.x，现在要PyTorch 2.x，直接用pip升级可能把系统里其他项目搞崩。用conda建一个干净的env，把3DGS的依赖全部锁在这个环境里，出问题随时删掉重来，不污染其他项目。

检查是否已经有conda环境，Windows下打开Anaconda Prompt，Linux下直接终端，输入conda --version看输出。没装的话去官网下载对应系统的安装包，一路默认安装即可。装完记得重新打开终端，让环境变量生效。

2.2 CUDA Toolkit和显卡驱动的关系

很多人把显卡驱动和CUDA Toolkit混为一谈。简单类比：显卡驱动是操作系统能识别显卡的“基础通道”，CUDA Toolkit是给开发者用的“开发SDK”，里面包含了编译器（nvcc）、CUDA运行时库、cuDNN等。你要编译和运行3DGS，两者都需要。

Windows上最容易出现的坑是：驱动是最新的，但没装CUDA Toolkit，或者装了但环境变量没配好，导致编译找不到nvcc。安装CUDA Toolkit时建议选自定义安装，勾选CUDA、Development、Runtime这些核心组件，其他不需要的组件可以不装。

安装完成后验证一下，Windows下打开cmd输入nvcc --version，Linux下同理。能输出版本号说明CUDA Toolkit装好了。如果提示找不到nvcc，检查环境变量里有没有C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8\bin（Windows），Linux下默认在/usr/local/cuda/bin。

2.3 Visual Studio的MSVC编译器是硬门槛

Windows下编译diff-gaussian-rasterization，本质是用MSVC编译C++代码，然后通过PyTorch加载成Python扩展。所以你必须安装Visual Studio，且必须勾选“使用C++的桌面开发”工作负载，里面那套MSVC工具链和Windows SDK都会被带上。

VS2022和VS2019都行，但要注意工具集版本。如果你用VS2019又装了个比较新的Windows SDK，编译时可能报一堆晦涩的MSB错误。我自己用的VS2022 + CUDA 11.8 + PyTorch 2.0.1这套组合跑通过，建议按这个来。

Linux用户不用装Visual Studio，但需要有C++编译器和CUDA相关的工具链，核心就是GCC和G++，Ubuntu上一般默认装了。关键是版本，如果GCC版本低于9，编译ext模块的时候会报GLIBCXX或者OpenMP相关错误，需要先升级编译器。

3. 实操：从零到一跑通3DGS

3.1 下载源码：这个坑必须提前避开

官方仓库地址是https://github.com/graphdeco-inria/gaussian-splatting，下载方式不是直接点Code按钮下载zip，那样会缺少submodule。必须用git克隆并带--recursive参数：

git clone --recursive https://github.com/graphdeco-inria/gaussian-splatting.git

为什么必须带--recursive？因为仓库里用了Git submodule来管理diff-gaussian-rasterization和simple-knn，这两个模块在third_party目录下，如果不拉下来，后面编译一定会报找不到文件。如果你已经不小心用了git clone没有--recursive，进目录执行：

git submodule update --init --recursive

同样能补救。这个坑我在帮朋友排查时遇到过至少三次，只要有一个人直接下载了zip包，后面必然报错。

3.2 创建conda虚拟环境并安装依赖

进入项目根目录后，先创建虚拟环境，名字随意，但Python版本建议用3.9：

conda create -n gaussian_splatting python=3.9 -y conda activate gaussian_splatting

然后安装PyTorch。这一步的关键是必须安装对应CUDA版本的PyTorch，不能用默认的CPU版本。以CUDA 11.8为例：

pip install torch==2.0.1 torchvision==0.15.2 --index-url https://download.pytorch.org/whl/cu118

这里需要解释一下为什么指定index-url。PyTorch官方默认推送的是CPU版本，如果你直接pip install torch，装出来的是不能用CUDA的，后面跑训练会一直报CUDA unavailable。指定--index-url就是为了明确告诉pip去下载带CUDA支持的wheel包。版本号2.0.1和CUDA 11.8是经过社区大量验证的稳定组合，不建议随意改。

3.3 安装其他Python依赖

官方提供了一个requirements.txt，直接安装即可：

pip install -r requirements.txt

里面包含submodules模块、open3d、pycolmap等依赖。但需要注意，requirements.txt可能需要看git版本，有些旧版本的requirements写法比较粗糙，如果报错提示找不到某个包，先看一下是不是Python版本问题。

如果网络不好，pip下载慢，可以加清华镜像源加速：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

3.4 编译扩展模块：最容易翻车的地方

diff-gaussian-rasterization和simple-knn不是预编译的，需要在本地编译成Python扩展。这一步是环境配置的核心难点，Windows和Linux处理方式略有不同。

Windows下，不要直接双击运行正常cmd，要打开“x64 Native Tools Command Prompt for VS 2022”，这个终端会自动加载MSVC和Windows SDK的环境变量。创建好conda环境后，在项目根目录下执行：

conda activate gaussian_splatting set DISTUTILS_USE_SDK=1 python setup.py install

set DISTUTILS_USE_SDK=1这个命令很关键。它的作用是让Python的setuptools在编译时使用Visual Studio的SDK环境，而不是尝试自己找一个编译器环境，能避免很多“找不到C++编译器”的报错。

Linux下要简单一些：

conda activate gaussian_splatting pip install submodules/diff-gaussian-rasterization pip install submodules/simple-knn

编译过程通常会输出一堆编译信息，看到“Successfully installed”才表示成功。如果中途报错，九成是CUDA路径没配好。确认一下系统环境变量里CUDA_HOME，Windows下是：

set CUDA_HOME=C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8

Linux下是：

export CUDA_HOME=/usr/local/cuda

如果编译报“No such file or directory”这种错误，大概率是CUDA_HOME设置了但路不对，逐级检查一下。

编译成功后，最直接的验证方式是：

python -c "import diff_gaussian_rasterization; print(diff_gaussian_rasterization.__file__)"

能打印出路径，说明模块装好了。没报错才是真正的成功。

3.5 准备数据：COLMAP位姿估计的坑

官方支持两种数据来源：一是你自己采集的图片，二是下载公开数据集（如Mip-NeRF 360、Tanks & Temples等）。自己采集图片的话，需要先用COLMAP做相机位姿估计，官方脚本convert.py能自动调用COLMAP完成这件事。

采集图片时注意几点：

• 图片分辨率控制在1.6k~2k左右，太高的分辨率会显著增加显存占用和优化时间。
• 场景光照尽量稳定，避免过度曝光和过暗，因为3DGS对初始化质量比较敏感。
• 图片数量不用太多，80~150张足够一个小场景，但角度要覆盖全面，避免有场景死角。
• 拍摄时尽量保持相邻图片有60%~70%的重叠率，COLMAP才能提取到足够的特征点。

Windows用户需要单独安装COLMAP并加入环境变量，Linux用户用apt安装也行。装好后测试一下：

colmap -h

能输出版本信息说明COLMAP可用。有的小伙伴下载了COLMAP最新版，但convert.py脚本里的调用接口变动导致报错，建议用3.6~3.8版本。

3.6 训练、渲染与评估一条龙

数据准备好之后，训练命令很简单：

python train.py -s data/your_scene -m output/your_scene

其中-s指定数据路径，-m指定输出路径。训练过程中会看到每100步打印一次PSNR等指标，整个训练默认3万次迭代，8GB显存大概需要1~3小时，24GB显存会快不少。

训练完成后，生成的点云模型和参数文件在output目录下。执行渲染和指标评估：

python render.py -m output/your_scene python metrics.py -m output/your_scene

render.py会生成每个视角的渲染图，metrics.py会计算PSNR、SSIM、LPIPS这三大评估指标。想看可视化效果，Windows下可以用项目自带的SIBR_viewer，Linux下需要自己编译SIBR_viewers，稍微麻烦一点，但如果你只是想确认效果，用render.py渲染出来的jpg图片就够了。

4. 常见问题与排查技巧实录

这一部分是我最想写的，因为配置环境时遇到的绝大多数问题都是重复出现的，如果把常见报错和解决思路整理成表，能帮大家省下大量排查时间。

4.1 高频报错速查表

4.2 训练过程中实际遇到的三个经典坑

**坑一：submodule为空目录。**一位朋友下载了zip包解压，进third_party/diff-gaussian-rasterization一看，里面空空如也。这种问题一旦遇到，问卷可能查不到答案，因为没人会想到你是这样下载代码的。按上文git submodule update --init --recursive补救就好。

**坑二：Windows下直接双击setup_win.bat报错。**官方其实提供了一个setup_win.bat，但它是个简单的封装，依赖当前终端环境。如果你双击，运行的是普通cmd，MSVC环境变量没加载进去，就会编译失败。一定要在x64 Native Tools Command Prompt里执行，或者先手动set DISTUTILS_USE_SDK=1。

**坑三：训练时PSNR和SSIM一直很低。**如果数据准备阶段COLMAP没跑好，相机位姿估计不准，训练出来的3DGS效果一定差。这时候看渲染图会发现物体是糊的，有重影。解决办法是重新拍摄照片或者调整COLMAP参数，重点是保证图像序列有足够的特征点和重叠度。

4.3 显存不足与训练速度的取舍心得

如果你只有8GB显存，又想跑自己的场景，我的实际经验是：

• 图片resize到1600，最长边不超过1600像素。
• 训练轮次从默认的30k降到15k，但要把保存间隔改小，比如每500步保存一次，这样即使中途显存爆了，还能从最近的checkpoint恢复。
• 用residual高斯策略不开的情况下，效果会下降一些，但速度提升很明显。日志里如果显示statistics buffer size过大，说明场景分割粒度太细，CPU内存也可能吃紧。
• 关闭TensorBoard的可视化，省一部分内存。
• Linux下可以用nvidia-smi查看当前GPU占用，如果其他用户/进程占了显存，就找管理员协调或者改用小模型。

4.4 环境配置的“最终手段”：完全重来

环境这个东西，有时候你排查很久也找不到原因，大概率是某个隐性的版本冲突。比如我之前遇到过一次Windows下PyTorch 2.1 + CUDA 12.1 + VS2022的组合，编译能过，但训练到几百步就崩，最后测试三个多小时，把PyTorch降回2.0.1就稳定了。

所以遇到疑难杂症，别死磕，果断删掉conda环境重来：

conda deactivate conda env remove -n gaussian_splatting conda create -n gaussian_splatting python=3.9 -y

然后按文章里的顺序重新来一遍。整个过程熟练之后大概半个多小时，比盲目排查几小时高效得多。

另外有一个小技巧：把用到的版本写在一个环境配置文件里（environment.yml），下次复现环境只需要input：

name: gaussian_splatting channels: - conda-forge dependencies: - python=3.9 - pip - pip: - torch==2.0.1 - torchvision==0.15.2

然后conda env create -f environment.yml，一步到位。配置环境这件事，本质上就是一套版本的组合拳。

5. 后续还能怎么玩

环境跑通只是第一步。3DGS这个方向现在衍生出了很多玩法：动态场景重建、自动驾驶多视角数据渲染、基于高斯的生成式模型、还有把3DGS用到SLAM里的。官方仓库只是最基础的一版，里面很多细节参数（比如sh_degree、densification_interval、opacity阈值）都值得慢慢调。

配置过程虽然繁琐，但一旦跑通，你会对整个深度学习和图形学的交叉工作流有更直观的理解。我个人的体会是：3DGS的环境配置本质上是一个工程化的“版本管理问题”，只要掌握了“先锁定版本组合，再按顺序安装、编译、验证”这套思路，后面遇到再新的项目也不慌。

最后再分享一个小习惯：每次配置环境前，先写一个简单的版本清单，把操作系统、显卡驱动、CUDA、Python、PyTorch、编译器版本全部记下来拍个照或者存个md文件。这样出了问题，能主动缩小排查范围。我自己后来配任何深度学习项目，都会先用这种方式做前置检查，少走了很多弯路。