WSL2搭建3DGS训练环境：CUDA/PyTorch版本匹配与避坑

折腾过3D高斯泼溅训练的人都清楚，真正让人掉头发的往往不是论文里的公式，而是环境。3D Gaussian Splatting这套流程对CUDA版本、PyTorch版本、C++编译器和显卡驱动的配合相当挑剔，错一个版本就可能卡在编译阶段一整天。Windows原生环境里，Python、Visual Studio、CUDA、PyTorch各自为政，路径里带空格、中文、反斜杠，随时能把构建脚本搞崩。我试过几轮之后，最终把训练环境整体搬进了WSL2，Windows只负责显卡驱动和日常操作，Linux子系统负责跑训练和编译。这篇内容就把我从零搭建这套环境的完整过程拆开讲清楚，包括为什么这么选、每一步在做什么、参数怎么定，以及那些文档里不会写、只有实际踩过才知道的坑。不管你是刚接触3DGS的新手，还是想在Windows机器上复用现有显卡跑训练的老手，都可以按这套流程直接抄作业。

1. 为什么把3DGS训练放进WSL2：方案选型与整体思路

1.1 3DGS训练对环境的真实要求

3D Gaussian Splatting的训练核心是一个自定义CUDA光栅化器，它需要在编译期链接CUDA运行时，在运行期调用GPU做大量并行的泼溅计算。这意味着环境必须同时满足几个硬条件：显卡驱动支持较新的CUDA运行时、PyTorch的CUDA版本与编译时用的CUDA工具包一致、系统里有可用的C++编译器、Python版本不能太新也不能太旧。官方代码对PyTorch和CUDA的版本组合有隐含要求，版本跨度太大时，自定义扩展的编译几乎必然失败。

除了编译，训练本身还吃显存和磁盘IO。一个中等规模场景，三万次迭代，显存占用轻松上到8GB以上，稠密化阶段峰值更高。数据加载和COLMAP重建阶段会频繁读写大量图片和特征文件，磁盘随机读写性能直接影响预处理时间。这些需求叠加起来，决定了环境不能只是“能跑”，还得“跑得稳、跑得快”。

我一开始在原生Windows上试，Python环境用conda管理，PyTorch能装上，但到了编译diff-gaussian-rasterization这一步就开始报错，核心原因是编译器版本和CUDA头文件路径对不上。后来换到WSL2，同样的显卡、同样的驱动，编译一次通过。这不是玄学，而是WSL2里的工具链更接近Linux服务器的标准形态，绝大多数开源项目的构建脚本都是照着Linux写的。

1.2 三种常见方案的实际对比

在Windows机器上跑3DGS，常见的选择无非三种：原生Windows、双系统Linux、WSL2。我把它们的实际体验整理成表，方便你按自己的情况选。

WSL2的核心优势在于它跑的是真正的Linux内核，GPU通过半虚拟化直通，CUDA调用几乎无损耗。我实测下来，同样的训练参数，WSL2和纯Linux的迭代速度差距在5%以内，日常完全够用。代价是跨文件系统访问会明显变慢，这一点后面会专门讲怎么规避。

1.3 整套环境的搭建路线图

动手之前先把路线理清楚，避免装到一半发现方向错了。整体分四层：最底层是Windows的虚拟化功能和显卡驱动，中间层是WSL2发行版和CUDA工具包，上层是conda管理的Python环境与PyTorch，最顶层才是3DGS代码和它的自定义扩展。

一个关键原则是：显卡驱动只装在Windows侧，WSL2内部不要再装一遍驱动。WSL2的GPU支持是通过Windows驱动暴露给子系统的，子系统里重复安装驱动会直接导致CUDA不可用。CUDA工具包则要装在WSL2内部，因为编译自定义扩展时需要nvcc和头文件。这个“驱动在宿主、工具包在子系统”的分工是整套环境稳定的前提，很多人卡在nvidia-smi能看到显卡但编译报找不到CUDA，就是这一步搞混了。

2. 底层环境准备：虚拟化、WSL2与显卡驱动

2.1 开启虚拟化并安装WSL2

第一步是在主板BIOS里确认虚拟化已开启，Intel平台找VT-x，AMD平台找SVM，不同主板叫法不一样，通常在CPU配置页里。没开虚拟化的话，WSL2装到一半会提示需要启用虚拟机平台，到时候再重启进BIOS更折腾。

系统层面，Windows 11直接以管理员身份打开终端，执行安装命令即可。Windows 10需要先确认版本号在2004以上，老版本不支持WSL2的GPU直通。

wsl --install

这条命令会默认装好WSL2内核和Ubuntu发行版。如果已经装过WSL但版本还是1，需要手动切换默认版本：

wsl --set-default-version 2

装完之后用wsl --list --verbose确认版本列显示为2。这里有个细节：如果你机器上之前装过Docker Desktop之类的工具，它可能自带一个WSL发行版，列表里会出现多个条目，训练环境建议单独用一个干净的Ubuntu，避免和其他工具的环境变量互相污染。

注意：安装过程中如果提示需要启用“虚拟机平台”和“适用于Linux的Windows子系统”两个Windows功能，勾选后必须重启，别跳过。

2.2 显卡驱动与CUDA工具包的正确分工

WSL2的GPU支持要求Windows侧安装较新的显卡驱动。判断驱动是否够新，最简单的办法是在WSL2里执行nvidia-smi，如果能正常列出显卡型号、显存和CUDA版本，说明直通没问题。这里显示的CUDA版本是驱动支持的最高运行时版本，不是实际安装的工具包版本，两者不要混淆。

CUDA工具包装在WSL2内部，推荐用官方提供的Linux仓库方式安装，版本选12.1或12.4这类与PyTorch官方轮子匹配较好的版本。安装时只勾选工具包和开发头文件，不需要装驱动组件。

wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb sudo dpkg -i cuda-keyring_1.1-1_all.deb sudo apt update sudo apt install cuda-toolkit-12-4

装完之后把CUDA路径写进环境变量，编辑~/.bashrc，追加两行：

export PATH=/usr/local/cuda-12.4/bin:$PATH export LD_LIBRARY_PATH=/usr/local/cuda-12.4/lib64:$LD_LIBRARY_PATH

执行source ~/.bashrc后，用nvcc --version确认编译器版本。这里的选择逻辑是：CUDA版本要略高于或等于PyTorch轮子自带的运行时版本，低太多会导致自定义扩展编译时报API不匹配。我选12.4是因为它能向下兼容多个PyTorch版本，后续换环境不用反复重装工具包。

2.3 WSL2的内存与磁盘配置调优

WSL2默认会占用宿主内存的一大块，训练时如果Windows侧还开着浏览器和设计软件，容易出现宿主和子系统抢内存的情况。在Windows用户目录下建一个.wslconfig文件，可以限制子系统的资源上限：

[wsl2] memory=32GB processors=12 swap=8GB localhostForwarding=true

内存上限建议设成物理内存的六成到七成，给Windows留足余量。处理器数量按物理核心数减二来配，避免子系统把宿主线程占满导致桌面卡顿。改完之后执行wsl --shutdown再重新进入，配置才生效。

磁盘方面，WSL2的虚拟磁盘默认放在系统盘，训练数据量大时容易把C盘撑满。可以用wsl --export和wsl --import把发行版迁移到剩余空间更大的数据盘。迁移前先关掉所有WSL进程，导出成tar文件再导入到目标目录，导入时记得指定新的虚拟磁盘位置。

2.4 文件系统选择：为什么训练数据不能放/mnt

这是WSL2环境里最容易忽视、影响又最大的一个点。WSL2访问Windows盘符是通过/mnt/c这类挂载点实现的，跨文件系统的每次读写都要经过一层转换，随机小文件读写性能会下降一个数量级。3DGS训练要反复读取图片、特征文件和点云缓存，放在/mnt下会让数据加载成为瓶颈，GPU利用率上不去。

正确做法是把代码和数据集全部放在WSL2自己的文件系统里，也就是/home/你的用户名/下面。从Windows侧访问这些文件可以通过资源管理器地址栏输入\\wsl$\加发行版名称，或者用VS Code的远程连接直接编辑，日常使用并不麻烦。

如果数据集原本在Windows盘上，用cp -r复制进/home，不要用软链接指向/mnt，软链接只是省了复制，实际读写还是走跨文件系统通道，性能问题照旧。我吃过这个亏，一开始图省事做了软链接，训练时GPU利用率只有四成，复制到本地目录后直接拉到八成以上。

3. 训练栈搭建：Python、PyTorch与3DGS依赖编译

3.1 用Miniconda隔离Python环境

系统自带的Python版本往往偏新，而3DGS的依赖对Python版本比较敏感，3.10到3.11是比较稳的区间。用Miniconda建独立环境，避免和系统包管理器打架。

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh

安装完成后重新打开终端，创建环境：

conda create -n gs3d python=3.10 -y conda activate gs3d

这里选3.10而不是更新的版本，原因是部分自定义扩展的构建脚本对较新的Python C API支持不完善，3.10的兼容性最好。环境建好之后，后续所有操作都在这个环境里进行，包括PyTorch安装和代码编译，切换环境时记得重新激活。

3.2 PyTorch与CUDA版本的匹配策略

PyTorch版本要和前面装的CUDA工具包对齐。假设工具包装的是12.4，PyTorch就选对应cu124的轮子。用conda安装时可以指定渠道，也可以直接用pip装官方轮子，后者版本更新更及时。

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

装完必须验证GPU是否可用：

python -c "import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))"

输出里cuda.is_available()必须是True，设备名称要能正确显示。如果这里是False，先回头检查WSL2里的nvidia-smi是否正常，再检查PyTorch是不是装成了CPU版本。很多时候是pip源里混入了CPU轮子，卸载重装指定cu版本即可。

提示：不要盲目追最新版PyTorch。3DGS的自定义扩展对PyTorch的C++接口有依赖，版本跨度过大时编译会报符号找不到。选官方代码发布时对应的版本区间最稳妥。

3.3 核心依赖编译：三个容易翻车的扩展

3DGS依赖三个需要现场编译的组件：diff-gaussian-rasterization、simple-knn，以及可选的图像处理库。编译过程会调用nvcc和gcc，任何一个版本不匹配都会失败。

先把代码拉下来，进入目录后安装子模块：

git clone https://github.com/graphdeco-inria/gaussian-splatting --recursive cd gaussian-splatting pip install -r requirements.txt

然后逐个安装子模块：

pip install submodules/diff-gaussian-rasterization pip install submodules/simple-knn

编译diff-gaussian-rasterization时最常见的报错是找不到CUDA头文件，或者提示nvcc fatal: Unsupported gpu architecture。前者是CUDA_HOME没设对，在环境变量里补上工具包路径即可；后者通常是显卡算力太老，需要在编译参数里显式指定架构。另一个高频问题是gcc版本过新，较新的gcc对某些C++标准的处理更严格，可以装一个gcc-11并切换默认版本。

simple-knn的编译相对简单，但如果前面PyTorch装的是CPU版本，这里会直接报找不到torch的CUDA扩展接口。所以编译前一定确认torch.cuda.is_available()为True。

3.4 环境自检清单

在正式训练之前，跑一遍自检，把问题提前暴露出来。检查项包括：nvidia-smi是否正常、nvcc --version是否输出、PyTorch的CUDA是否可用、两个自定义扩展能否正常导入。

python -c "import diff_gaussian_rasterization; import simple_knn; print('extensions ok')"

能打印出extensions ok，说明编译链和运行时都通了。如果导入时报共享库找不到，多半是LD_LIBRARY_PATH没包含CUDA的lib64目录，回头检查环境变量。这个自检清单看着简单，但能挡住后面八成的环境类报错。

4. 数据准备与完整训练流程

4.1 从图片到COLMAP稀疏重建

3DGS的输入不是直接给图片，而是需要相机位姿和稀疏点云。标准流程是用COLMAP做运动恢复结构，输出每张图的相机参数和一个稀疏点云。WSL2里装COLMAP直接用包管理器：

sudo apt install colmap

数据准备分四步走：特征提取、特征匹配、稀疏重建、图像去畸变。假设图片放在images/目录，输出到sparse/：

colmap feature_extractor --database_path db.db --image_path images colmap exhaustive_matcher --database_path db.db mkdir sparse colmap mapper --database_path db.db --image_path images --output_path sparse mkdir undistorted colmap image_undistorter --image_path images --input_path sparse/0 --output_path undistorted

exhaustive_matcher适合几十到几百张图的规模，图片上千时匹配时间会暴涨，可以换成顺序匹配或词汇树匹配。重建完成后检查sparse/0下是否生成了相机文件和点云文件，如果点云为空，说明图片重叠度不够或者纹理太弱，需要补拍。

4.2 训练参数的含义与取值逻辑

官方训练脚本的参数不少，真正影响效果和资源占用的就那么几个。下面这张表是我常用的参数组合及调整依据。

训练命令的基本形态：

python train.py -s /home/user/data/scene -m /home/user/output/scene_run1 --iterations 30000

-s指向去畸变后的数据目录，里面要有images和sparse两个子目录；-m是输出目录，模型权重、点云和日志都会写到这里。分辨率参数在显存不足时最管用，设成2意味着长边缩到一半，显存占用大约降到四分之一，代价是细节损失。

4.3 训练过程监控与显存控制

训练启动后，终端会按迭代轮次打印损失和点数量。点数量在稠密化阶段会快速上涨，从几万个涨到几百万是常态。显存占用和点数量正相关，峰值通常出现在稠密化中后期。

监控显存最直接的办法是另开一个WSL终端跑watch -n 1 nvidia-smi，观察显存曲线。如果显存接近上限并开始出现分配失败，说明稠密化过猛，可以调低--densify_until_iter或者提高--densification_interval。还有一个不太为人知的参数是--percent_dense，它控制稠密化的密度阈值，调低会减少新增点数量，对显存紧张的场景有效。

训练中断了也不用从头来，输出目录里会定期保存检查点，用--start_checkpoint指向最近的检查点文件可以续训。不过续训时优化器状态会重置一部分，效果和连续训练略有差异，能一次跑完尽量一次跑完。

4.4 渲染输出与结果查看

训练完成后，用渲染脚本生成新视角图像：

python render.py -m /home/user/output/scene_run1

渲染分训练视角和测试视角两部分，输出在模型目录的train和test子文件夹里。想看动态效果需要编译实时查看器，它对图形环境有要求，WSL2里跑需要配置X服务器转发，比较折腾。更省事的做法是把输出目录里的点云文件复制到Windows侧，用支持PLY格式的查看器打开，或者把渲染出的图片序列合成视频直接看。

质量评估脚本会计算PSNR、SSIM等指标，前提是数据目录里有对应的测试集划分。指标只能作为参考，实际观感更重要，尤其是边缘和反光区域的伪影，指标不一定能反映出来。

5. 高频问题排查实录

5.1 编译阶段的典型报错与处理

编译类问题占了环境搭建故障的一大半，下面这几个是我实际遇到并记录下来的。

处理这类问题的通用思路是先看报错的第一行，那通常是根因，后面的连锁报错都是衍生品。比如看到undefined symbol就不要再折腾CUDA路径了，问题在PyTorch版本上。

5.2 显存不足与训练崩溃

显存不足的表现是训练中途报CUDA out of memory，进程直接退出。排查顺序是：先看当时迭代到哪一步，如果是在稠密化阶段，基本可以确定是点数量涨太快；如果是一开始就崩，可能是分辨率太高或者批量大小设置问题。

应急处理有三个方向：降分辨率、提前停止稠密化、减少同时加载的数据量。长期方案是换更大显存的卡，或者把场景分块训练再合并。还有一个容易忽略的点是WSL2的内存配置，如果.wslconfig里给子系统分配的内存太小，系统层面的内存不足也会伪装成CUDA错误，日志里会混着内存分配失败的提示。

5.3 路径、权限与跨文件系统问题

WSL2里的权限问题和路径问题经常结伴出现。典型场景是从Windows侧复制数据进子系统，文件属主变成了root，普通用户读写不了。用chown -R改回自己的用户即可。另一个场景是路径里带空格或中文，COLMAP和训练脚本对这种路径的处理不一致，最稳妥的做法是数据目录全用英文和短横线命名。

跨文件系统的问题前面提过，这里再强调一次：训练数据、输出目录、代码目录三者都放在/home下，不要出现任何指向/mnt的软链接。输出目录尤其重要，训练过程中会高频写入检查点和日志，写在/mnt下不仅慢，还可能因为Windows侧的文件锁导致写入失败。

5.4 图形显示与查看器的替代方案

WSL2默认没有图形界面，实时查看器需要OpenGL上下文，直接跑会报显示相关的错误。配置X服务器转发能解决，但延迟和兼容性都不理想，尤其是需要交互旋转视角的时候。

我的做法是放弃在子系统里看实时效果，训练和渲染都在WSL2里完成，把渲染出的图片序列或者导出的点云文件拿到Windows侧查看。图片序列用普通播放器就能看，点云文件用支持PLY的轻量查看器打开，足够判断训练质量。如果确实需要交互式查看，可以把模型目录整体复制到Windows侧，在那边跑查看器的可执行版本，省去图形转发这一层折腾。

注意：复制模型目录时要把点云文件和相机参数一起带走，只复制PLY文件的话查看器可能无法正确初始化视角。

这套环境我从第一次搭建到现在反复重装过好几次，每次换机器或者升级驱动都会重新走一遍流程。最大的体会是版本锁定比追新重要得多，把CUDA、PyTorch、gcc这三个版本记在一个文档里，下次重装直接照抄，能省掉大量试错时间。另外，训练数据一定要放在子系统自己的文件系统里，这个习惯一旦养成，后面几乎所有性能问题都不会再找上门。环境搭好只是第一步，真正花时间的还是数据采集和参数调优，那部分就得靠一个个场景慢慢磨了。