好先说结论COLMAP 3.13.0 CUDA 12.9 Ubuntu 24.04这套组合你要是对着官方文档一步步来大概率要卡在“依赖装完、CMake 跑挂”这个最磨人的环节上。我自己在这套环境里前前后后折腾了一整个周末踩了 Qt、Ceres、CUDA 架构算力不匹配三个大坑之后才顺利编过。这篇就把整个过程中的关键决策、完整命令和报错排查方案整理出来如果你也正准备在这套组合下从源码编译 COLMAP直接照着走能省掉至少半天时间。COLMAP 是做三维重建绕不开的工具SfM运动恢复结构和 MVS多视角立体匹配的完整流程都在里面支持特征提取、匹配、稀疏重建、稠密重建、网格生成和纹理映射。3.13.0这个版本发布后最大的变化之一是加强了对新版本 CUDA 和 Qt6 的适配同时也开始对较新的 CMake 和 GCC 版本做更严格的约束——这意味着在 Ubuntu 24.04 上编译很多历史教程里的“老方案”已经不适用了必须按新版本的要求重新组合依赖参数。这篇文章的内容是基于我自己的实测所有命令都在一台干净安装的 Ubuntu 24.04.1 LTS 上执行过显卡是 RTX 4060 Ti16GB驱动用的是 550 系列。你在实际操作时只要显卡架构是 RTX 20 系及以上步骤可以完全照搬。1. 环境准备这一套编译链的核心思路1.1 为什么要从源码编译而不直接用 apt 装Ubuntu 24.04 官方软件源里的 COLMAP 版本是 3.7说好听点叫“稳定”说难听点就是个能用但没跟上新算法的老古董。CUDA 加速能力和新版本差得不是一点半点而且你在三维重建里如果要用到一些新出的特征提取器3.7 根本不支持。另外 apt 装的 COLMAP 默认只开启了 CPU 模式也就是说你花了大几千买的 NVIDIA 显卡在跑稠密重建时就是摆设那速度你会怀疑人生。所以我建议在有独立 NVIDIA 显卡2GB 显存以上的设备上一律从源码编译把 CUDA 后端完整打开。1.2 需要预先准备的硬件和系统条件在动手装依赖前先检查三样东西显卡驱动是否已正确安装执行nvidia-smi能正常显示 GPU 信息Ubuntu 版本确认是 24.04lsb_release -a查看磁盘空间至少预留 20GB编译中间文件占的空间比你想象的大你如果用的是笔记本双显卡注意在安装 NVIDIA 驱动前把 BIOS 里的显卡模式调成“独显直连”或者至少让 Linux 能看到独显。有些没设置好的双显卡机器nvidia-smi会直接报错后边全白搭。1.3 CUDA 12.9 与 Ubuntu 24.04 的兼容性说明CUDA 12.9 是 2025 年 3 月发布的版本对 Ubuntu 24.04 的支持是官方明确的。安装时不要用什么apt install cuda一把梭也不要通过那种 third-party 的 PPA 装老老实实从 NVIDIA 官网下载 runfile 安装最稳妥。我在测试中发现Ubuntu 24.04 默认的 GCC 是 13.2CUDA 12.9 官方支持的最高 GCC 版本是 14.x意味着系统自带的 GCC 可以直接拿来用不需要像老版本 CUDA11.x那样还要单独装 GCC 10 或者 9。这一点也算是这套组合的一个优势省了一项蛋疼配置。还有很重要的一点不要用apt install nvidia-cuda-toolkit这个包在 Ubuntu 仓库里乱七八糟的老早就不维护了版本落后不说还会把整个编译链的依赖关系搞得一团糟。我见过不少人在这一步贪方便结果到编译 COLMAP 的时候CMake 死活找不到 CUDA 的 runtime最后又得重新清理环境白白浪费两小时。2. 依赖安装详解三类依赖的取舍与安装方案2.1 核心依赖组常规工具链COLMAP 编译需要的基础工具链包括build-essential、git、cmake、ninja-build、g。这里有个关键点Ubuntu 24.04 软件源里的 CMake 版本是 3.28.3而 COLMAP 3.13.0 的官方要求是CMake 3.21所以直接用 apt 装的 CMake 也完全够用不需要自己手动去编译 CMake不过确实有人明明装了新 CMake却因为没把路径配好导致系统在调老版本后面 CMake 阶段会有各种诡异报错。Ninja 建议装上因为 COLMAP 官方推荐用 Ninja 作为生成器比默认的 Unix Makefiles 编译速度快很多多核并行效率也更高。sudo apt update sudo apt install -y \ build-essential \ git \ cmake \ ninja-build \ g \ pkg-config \ unzip2.2 CUDA Toolkit 12.9 安装与 PATH 配置CUDA 安装是整套流程里最容易出问题的环节也是最核心的。我用的安装方式是官网的 runfile到 NVIDIA 官网的 CUDA Toolkit 下载页选择 Linux → x86_64 → Ubuntu → 24.04 → runfile (local)下载完成后执行sudo sh cuda_12.9.0_550.xx.xx_linux.run安装时会提示你是否安装驱动这里不要勾选驱动安装。为什么因为 runfile 里的驱动版可能跟你的显卡不匹配特别是新出的卡而且你已经装好了 550 系列驱动重复装会出现驱动冲突。只需要安装 CUDA Toolkit 本身即可。安装完成后关键一步是配置环境变量# 在 ~/.bashrc 末尾添加 export PATH/usr/local/cuda-12.9/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda-12.9/lib64:$LD_LIBRARY_PATH执行source ~/.bashrc后运行nvcc --version验证版本nvcc: NVIDIA (R) Cuda compiler driver Copyright (c) 2005-2025 NVIDIA Corporation Built on Mon_Mar_17_22:03:15_PDT_2025 Cuda compilation tools, release 12.9, V12.9.xxx2.3 图像与几何处理相关依赖COLMAP 依赖很多图像 I/O 和几何处理库这些建议全部用 apt 安装版本匹配度高不用自己折腾sudo apt install -y \ libboost-program-options-dev \ libboost-filesystem-dev \ libboost-graph-dev \ libboost-system-dev \ libboost-test-dev \ libeigen3-dev \ libflann-dev \ libfreeimage-dev \ libmetis-dev \ libgoogle-glog-dev \ libgtest-dev \ libsqlite3-dev \ libglew-dev \ libqt5opengl5-dev \ libcgal-dev \ libfmt-dev \ libceres-dev注意最后这个libceres-devUbuntu 24.04 仓库里带的是 Ceres Solver 2.2.0能兼容 COLMAP 3.13.0但后边编译陶瓷时要用到它的库文件路径这里装的版本能不能行关键要看 CMake 能不能搜到。实测下来是可以的不过如果你在 CMake 配置阶段发现找不到 Ceres就需要手动从源码编译 Ceres见后面的常见问题。2.4 GUI 相关的 Qt 依赖争议点COLMAP 的图形界面基于 Qt3.13.0 同时支持 Qt5 和 Qt6。在 Ubuntu 24.04 上apt 默认的 Qt 版本是 Qt6但实测用 Qt6 编译时FLANN、QGLViewer 之类的组件在链接阶段有概率出问题而且编译报错信息非常隐晦。我的建议是装 Qt5稳定省心sudo apt install -y \ qtbase5-dev \ libqt5opengl5-dev \ libqt5printsupport5-dev \ libqglviewer-dev-qt5 \ libqt5svg5-dev这里有个细节libqglviewer-dev-qt5这个包名一定要带-qt5后缀Ubuntu 24.04 仓库里还有不带后缀的 Qt6 版本libqglviewer-dev如果你两个都装了CMake 搜索依赖时会出现混乱。这也是我在实际部署中踩过的一个坑明明 Qt 配置都正常但 CMake 就是报Could NOT find QGLViewer查了半天才发现是两个版本冲突。3. COLMAP 源码编译全流程从拉取代码到 CUDA 架构配置3.1 获取源码并准备编译目录通过 Git 拉取 COLMAP 3.13.0 的源码我建议用 tag 修订版本而不是拉最新的 master 分支因为 master 上可能有还没稳定下来的改动编译过不过全看脸git clone https://github.com/colmap/colmap.git cd colmap git checkout 3.13.0 mkdir build cd build3.2 CMake 配置阶段的关键参数解析CMake 配置是整个编译过程中最讲究的一步。COLMAP 的构建系统会用 CMake 的find_package去搜索依赖你把参数配错了往往到了编译后期才发现返工成本极高。我实际使用的配置命令如下cmake .. -G Ninja \ -DCMAKE_BUILD_TYPERelease \ -DCMAKE_CUDA_ARCHITECTURESnative \ -DCUDA_ENABLEDON \ -DCMAKE_CUDA_COMPILER/usr/local/cuda-12.9/bin/nvcc逐项解释一下这些参数背后的考虑-DCMAKE_BUILD_TYPERelease编译优化模式Release 模式会开启-O3优化跑三维重建时速度提升明显-DCMAKE_CUDA_ARCHITECTURESnative这个参数极其关键。它告诉 CMake 根据当前机器的 GPU 架构来生成对应的 SASS 汇编。CMake 3.28 之后对老的-DCMAKE_CUDA_FLAGS传架构方式不再友好你用native是最省心的。但注意native依赖nvcc能正确识别当前 GPU即编译出来的二进制只能在自己机器上跑换显卡机器就得重新编-DCUDA_ENABLEDON开启 CUDA 支持这也是源码编译的核心价值-DCMAKE_CUDA_COMPILER显式指定 nvcc 路径防止 CMake 去找系统其他版本的 CUDA。如果确认 CMake 输出内容里能看到CUDA detected,Found CUDA等字样并且列出了你的 GPU 架构编号比如compute_89对应 RTX 40 系那配置阶段就算过了。还有一个可选项-DGUIVIEW_ENABLEDON默认是开的如果你不需要 GUI只想用命令行工具做特征提取和重建可以关掉能省不少编译时间和磁盘空间。但绝大多数人还是需要 GUI 来可视化点云和位姿所以建议保留。3.3 编译过程与资源限制配置完成后直接执行 Ninja 编译ninja第一次编译时CMake 会把所有依赖的编译任务一起编排好整个编译过程大概需要 15~30 分钟视 CPU 核心数而定。我自己的机器是 8 核 16 线程Ryzen 7 5800X编译全程大概 18 分钟。如果你 CPU 核心少可以限制并行任务数避免内存不够导致 OOMninja -j4注意编译过程出现internal compiler error时往往不是代码问题而是内存不够。Ninja 默认会打满所有 CPU 核心每个编译任务约占用 1~2GB 内存建议系统内存低于 16GB 时用-j4内存 32GB 以上再用默认并行度。编译结束后验证产物是否正确生成ls -lh src/colmap/exe/colmap如果看到colmap可执行文件说明核心编译已经完成。3.4 安装到系统目录sudo ninja install安装完成后运行colmap -h验证。正常输出会显示 COLMAP 3.13.0 的版本信息以及一条[CUDA]相关的日志如果你在编译时正确开启了 CUDACOLMAP 3.13.0 -- Structure from Motion and Multi-View Stereo [] CUDA is enabled这条[] CUDA is enabled是新版本专门加的提示看到它就说明 CUDA 硬件加速已经成功编译进去了。4. 核心体验与实操验证跑通一个室内场景重建4.1 准备测试数据集编译通过只是起点就像把工具箱买回来真正要看的是工具能不能干好活。我用的是自己用旧手机小米 10 的 4800 万像素主摄拍的室内桌面场景共 12 张照片。这套数据足够验证整个 SfM 流程是否正常跑通。4.2 特征提取与匹配进入数据目录先做特征提取colmap feature_extractor \ --database_path database.db \ --image_path images \ --ImageReader.single_camera 1 \ --SiftExtraction.use_gpu 1注意最后那个--SiftExtraction.use_gpu 1SIFT 特征提取是可以用 CUDA 加速的实测 CPU 上跑 12 张 4000x3000 的图片大概要 40 秒GPU 上只要不到 5 秒。如果这个参数不加或者编译时没开启 CUDA你看到这条命令执行时会走 CPU 模式速度天差地别。然后进行特征匹配colmap exhaustive_matcher \ --database_path database.db \ --SiftMatching.use_gpu 1exhaustive_matcher适合图像数量少≤500 张的场景对每两张图片都做特征匹配精度高但计算量是 O(n²)。如果图像数量多可以考虑sequential_matcher或vocab_tree_matcher这些都是 COLMAP 3.13.0 自带的功能。4.3 稀疏重建与模型导出mkdir sparse colmap mapper \ --database_path database.db \ --image_path images \ --output_path sparse这一步会基于前面提的特征点对做增量式 SfM输出一组.bin格式的稀疏模型。在 12 张图上大概只需要 1~3 分钟跑完之后sparse/0/这个目录下会生成cameras.bin、images.bin、points3D.bin三个文件。验证重建质量可以用以下命令把相机位姿输出成文本格式colmap model_converter \ --input_path sparse/0 \ --output_path sparse/0/txt \ --output_type TXT然后打开sparse/0/txt/images.txt能看到每张图片对应的相机外参四元数 平移向量。如果你的 12 张照片里至少有 10 张被成功注册图片文件名出现在 images.txt 里说明整个编译环境已经完全能用于实际重建任务了。4.4 稠密重建验证这是吃显卡的大户mkdir dense colmap image_undistorter \ --image_path images \ --input_path sparse/0 \ --output_path dense \ --output_type COLMAP colmap patch_match_stereo \ --workspace_path dense \ --PatchMatchStereo.geom_consistency truepatch_match_stereo这一步是纯 CUDA 计算RTX 4060 Ti 跑 12 张图大概需要 5 分钟。如果你的编译没有正确启用 CUDA这一步会直接报错CUDA not available或者干脆提示No CUDA device found。能正常跑完说明从 CUDA 安装到 COLMAP 编译全链路都没有问题。5. 常见编译错误大盘点与解决方案下面这些错误是我在实际安装和帮助其他朋友排查时遇到的高频问题整理出来供你对照排查。5.1 CMake 阶段报找不到 CUDA报错特征CMake Error at cmake/FindCUDA.cmake:... Could NOT find CUDA: Found unsuitable version...原因与解决方案大概率是 CMake 在PATH里找不到nvcc或者PATH指到了旧版本 CUDA。先检查which nvcc nvcc --version如果没有输出或版本不对检查~/.bashrc里的export PATH/usr/local/cuda-12.9/bin:$PATH是否确实生效。我的经验是很多人在修改~/.bashrc后忘记source ~/.bashrc新终端明明已经开了CMake 却是在老终端里跑的导致查不到。5.2 编译中段报cannot find -lceres或undefined reference to ceres报错特征/usr/bin/ld: cannot find -lceres collect2: error: ld returned 1 exit status原因与解决方案Ceres Solver 库没有正确安装或者版本不对。先执行ls /usr/lib/x86_64-linux-gnu/libceres*如果找不到libceres.so说明libceres-dev没装好重新安装。如果确实存在但还是链接失败先用apt info libceres-dev看版本是否为 2.2.0。低于 2.0 的话建议手动编译 Ceresgit clone https://github.com/ceres-solver/ceres-solver.git cd ceres-solver mkdir build cd build cmake .. -G Ninja -DCMAKE_BUILD_TYPERelease ninja sudo ninja install装完后再重新编译 COLMAP记得先清理 build 目录rm -rf * cmake .. -G Ninja ...5.3 GUI 显示配置时报 Qt5 相关错误报错特征Could NOT find Qt5 (missing: Qt5OpenGL Qt5PrintSupport)原因与解决方案Qt 5 相关开发包没装全。把上面列的 qt 那一条安装命令重新执行一遍重点检查libqt5opengl5-dev和libqt5printsupport5-dev是否安装成功。Ubuntu 24.04 上还有一种特殊情况系统默认 Qt6 存在CMake 优先找到了 Qt6 而不是 Qt5导致 Qt5 相关检测失败。这时可以在 cmake 命令里强制指定-DQt5_DIR/usr/lib/x86_64-linux-gnu/cmake/Qt55.4CUDA_ARCHITECTURES报错报错特征CMake Error: CUDA_ARCHITECTURES must be non-empty原因与解决方案CMake 在检测 GPU 架构时没有找到匹配项。这种问题通常出现在老显卡比如 GTX 10 系或者 APU 平台上。此时需要手动指定架构编号比如 RTX 3080 是compute_86RTX 4060 Ti 是compute_89GTX 1080 Ti 是compute_61-DCMAKE_CUDA_ARCHITECTURES895.5 链接阶段报undefined reference to __cudaRegisterBinary报错特征undefined reference to __cudaRegisterBinary原因与解决方案这一步严格来说不是 COLMAP 的锅是你的 CUDA 环境变量配置有误LD_LIBRARY_PATH没有指向 CUDA 的 lib64。检查echo $LD_LIBRARY_PATH确认/usr/local/cuda-12.9/lib64在输出中。如果为空回到第二节重新配置环境变量。6. 留给后来者的几条实用经验6.1 关于 CUDA 多版本共存的处理不少人的机器上可能有多个 CUDA 版本比如之前装过 11.8 后来升到 12.9这种情况下手动指定编译器和库路径尤为重要。我在测试机上同时装了 CUDA 11.8 和 12.9用软链接的方式切换sudo rm /usr/local/cuda sudo ln -s /usr/local/cuda-12.9 /usr/local/cuda这样做的好处是/usr/local/cuda始终指向一个当前要用的版本。编译 COLMAP 时-DCMAKE_CUDA_COMPILER/usr/local/cuda/bin/nvcc无论切到哪个版本都不需要改代码非常优雅。6.2 关于编译后二进制文件的可移植性统计一下这里的坑COLMAP 3.13.0 编译时如果指定了-DCMAKE_CUDA_ARCHITECTURESnative生成的二进制只在当前 GPU 架构上运行。假设你编完想拷到另一台显卡架构不同的机器上运行时会出现no kernel image is available for execution on the device的报错。解决思路如果你需要在多台机器上分发使用编译时不要指定 native而是用一组兼容架构列表-DCMAKE_CUDA_ARCHITECTURES61;70;75;80;86;89这样生成的二进制兼容从 Volta 到 Ada 的几乎所有 NVIDIA 显卡。当然了代价是编译时间翻倍。6.3 编译产物体积与清理建议CUDA 开启后COLMAP 二进制文件体积相当可观实测colmap可执行文件有 250MB 左右Release 模式Debug 模式能超过 1GB。这是正常的不需要担心。如果磁盘空间紧张编译完成后可以直接删掉 build 目录只保留/usr/local/bin/colmap即可。7. 遇到再解决不了时的兜底思路如果你按照上面的步骤操作依然在某个环节卡住不要直接放弃。有几个思路比反复重装系统更有效第一查阅 COLMAP 官方文档的 Installation 页面。3.13.0 版本的文档比老版本完善了很多里面专门列出了 Ubuntu 24.04 的依赖清单和 CMake 参数模板值得逐行对照。第二把报错信息中CMake Error之前的全部上下文复制到 GitHub Issues 搜索。COLMAP 项目非常活跃绝大多数编译问题都已经有人提问过直接搜索repo:colmap/colmap 3.13.0 build Ubuntu 24.04常能找到完全匹配的场景和你需要的解决方案。第三我自己的一个习惯在 cmake 配置时加-DCMAKE_VERBOSE_MAKEFILEON或者在 Ninja 编译时加ninja -v让编译过程把每一步实际执行的命令完全打出来排查链接错误时能精确知道是哪个库没找到。别小看这个参数它救过我好多次。