简介这是基于 OpenSceneGraph 3.6.5 构建的 osgEarth 3.4.0 64 位自编译版目标环境为 Visual Studio 2022使用 vcpkg 完成依赖安装与编译适合在 Windows 平台开发地形渲染、地图可视化等三维 GIS 应用的 C 程序员使用。资源同时提供 Debug 和 Release 两种模式配套 EXE 可执行文件、LIB 静态库、DLL 动态库与 PDB 调试符号Debug 版便于逐步断点排错Release 版则兼顾运行效率解压后可直接被 CMake 工程引用省去手工编译 OSG 和 osgEarth 的繁琐过程。压缩包共 2000 个文件其中 1948 个 H 头文件与 47 个 HPP 文件构成主要开发接口另有 TXT、PDF、MD 等使用说明包体大小约 483.88MBinclude、lib、bin、cmake 子目录划分清楚便于定位所需模块。已有 1239 人浏览学习适合希望快速上手 osgEarth 并在此基础上开展功能调试与性能优化的中高级开发者。整套自编译结果特别适合作为独立依赖层集成进既有三维渲染项目既避免了从源码逐项编译带来的依赖冲突也保留了 PDB 调试符号等关键信息是开展三维地理信息项目时一份完备的二进制依赖包。 真正搞过 OSG 的人都知道官方预编译包和实际项目需求之间总隔着一道坎版本对不上、编译器 ABI 不兼容、插件缺东少西。我这次用 VS2022 64 位环境自编译了 OSG 3.6.5 和 osgEarth 3.4.0Debug 和 Release 双配置全部过一遍整个过程踩了不少坑也总结了一套可以照着抄的流程。这篇就把完整的编译过程、CMake 配置要点、常见链接和运行问题一次讲清楚给后面要在这套组合上做 GIS 或三维渲染项目的朋友省点时间。我自己用的是 Windows 11 专业版 Visual Studio 2022 Community不需要折腾产品密钥社区版已经够用。CMake 用 3.22 以上版本Git 客户端用于拉取源码和第三方库。这套组合稳定跑了好几个月至少在我的场景下没有出现过莫名其妙的崩库问题。只要你的操作系统是 64 位这套流程基本可以复现。1. 项目概述与编译环境准备1.1 为什么非要自己编译一套 DebugRelease如果你只是写个简单的 OSG 程序官方预编译包也许够用。但一旦涉及 osgEarth 这种依赖较多的大型库预编译包的 AppVeyor 构建配置和你的项目往往存在细微差异最常见的就是/MD和/MDd运行时库混用导致链接报错或者某个第三方库版本太老功能缺失。自编译的最大价值在于可以把 Debug 和 Release 两套产物都牢牢握在手里。Debug 版用于日常断点调试Release 版用于最终发布。两套库保持相同的源码版本和依赖版本切换配置时不会出现奇怪的行为差异。osgEarth 这种底层渲染引擎运行时的符号一致性和稳定性格外重要这也是我坚持自编译的核心原因。另外自编译还能按需裁剪。不需要的插件可以关掉比如我不需要 VRML 和 DAE 相关的旧插件直接在 CMake 里禁用减少编译时间也让最终安装目录更清爽。1.2 环境清单与工具版本组件版本说明操作系统Windows 11 专业版 22H264 位Win10 同样支持但要注意第三方库的 SDK 版本Visual Studio2022 Community 17.8需要安装“使用 C 的桌面开发”工作负载CMake3.27.7推荐 3.22 以上避免 osgEarth 的 CMakeLists 语法兼容问题Git2.42.0拉取源码和部分第三方库第三方库见 2.3 节Debug/Release 都要有对应版本VS2022 安装的时候记得勾选 Windows 10/11 SDK 和 CMake 工具。如果之前没装 CMake可以直接从官网下载安装包安装时选择“Add CMake to the system PATH for all users”。2. 源码与第三方依赖项准备2.1 获取 OSG 3.6.5 和 osgEarth 3.4.0 源码OSG 3.6.5 是 OpenSceneGraph 3.6 系列中比较稳定的版本osgEarth 3.4.0 刚好适配这条主线。在 GitHub 上拉取对应 taggit clone --branch OpenSceneGraph-3.6.5 https://github.com/openscenegraph/OpenSceneGraph.git git clone --branch osgEarth-3.4 https://github.com/gwaldron/osgearth.git osgearth-3.4.0osgEarth 仓库的 tag 命名不一定全是 3.4.0 这种形式实际以分支osgEarth-3.4为准。源码路径建议不要带中文和空格我放在D:/work/src/OpenSceneGraph-3.6.5和D:/work/src/osgEarth-3.4.0后续 CMake 生成时能少很多路径转义问题。2.2 第三方库整理策略编译 OSG 和 osgEarth 最痛苦的部分是第三方依赖。osgEarth 3.4.0 依赖 OSG、GDAL、CURL、GEOS、SQLite3、Protobuf、QThread 等而 OSG 本身依赖 ZLIB、LIBPNG、LIBJPEG、TIFF、FREETYPE、CURL 等。第三方库的获取有两条路线一是使用 vcpkg 统一管理二是手动下载预编译库。我这次用的是手动预编译库的方式因为 vcpkg 在高版本 VS 下对旧库的编译调整比较大容易把时间耗在修 vcpkg 的 port 上。手动获取时推荐两个来源OpenSceneGraph 官方 3rdParty 仓库的 64 位预编译库GIS 生态常用的osgEarth 3rdParty 库包含 GDAL、GEOS、CURL、SQLite3 等这里有一个关键点必须确认所有第三方库都是 64 位版本。如果你混合了 32 位库CMake 配置时可能不报错但链接阶段会报unresolved external symbol或者LNK2038。如何快速确认库的位数用 Visual Studio 开发者命令行工具执行dumpbin /headers C:\path\to\library.lib | findstr machine输出x64就是 64 位库x86或AMD64要按实际输出判断。dumpbin只认 PE 头格式这招比直接猜靠谱得多。2.3 目录规划建议建议把所有第三方库统一放到D:/work/3rdParty下按库名建子目录每个库内部按include、lib、bin三层组织。这样做的好处是 CMake 里指定路径时非常清晰不会出现“每个库路径都不一样”的混乱局面。我自己的目录结构长这样D:/work/3rdParty/ zlib-1.2.13/ include/ lib/ bin/ gdal-3.6.3/ include/ lib/ bin/ curl-8.0.1/ include/ lib/ bin/ ...3. OSG 3.6.5 编译实战3.1 CMake 配置关键参数在 CMake GUI 里设置源码目录和构建目录比如构建目录设为D:/work/build/OSG-3.6.5-build。点击 Configure选择 Visual Studio 17 2022平台选 x64然后打开分组视图逐项检查以下变量变量推荐值说明ACTIVE_3D_ONLYOFF如果不需要 OpenVR 等 3D 设备支持可以关掉BUILD_OSG_APPLICATIONSON编译 osgversion、osgviewer 等工具BUILD_OSG_PLUGINSON必须开启DYNAMIC_OPENTHREADSON动态库方式DYNAMIC_OPENSCENEGRAPHON动态库方式CMAKE_INSTALL_PREFIXD:/work/install/OSG-3.6.5安装根目录CMAKE_CONFIGURATION_TYPESDebug;Release确保 VS 里能切换配置如果你有第三方库需要在这个界面最下方找到ZLIB_INCLUDE_DIR、ZLIB_LIBRARY、GDAL_INCLUDE_DIR、CURL_INCLUDE_DIR等变量逐一点过去选择对应路径。全部配置完成后点 Generate。3.2 Debug 和 Release 的批量编译生成 VS 工程后最直接的方式是打开OpenSceneGraph.sln在解决方案管理器里右键ALL_BUILD分别切换 Debug 和 Release 配置点击生成。但手动点两次很费时间我更推荐用命令行一次跑完cmake --build D:/work/build/OSG-3.6.5-build --config Debug --parallel 8 cmake --build D:/work/build/OSG-3.6.5-build --config Release --parallel 8编译 OSG 需要一段时间--parallel 8可以加快速度。我在 12700F 处理器上编译 Debug 大约 12 分钟Release 大约 9 分钟具体时间取决于插件开关数量。编译结束后一定要安装到指定目录cmake --install D:/work/build/OSG-3.6.5-build --config Debug cmake --install D:/work/build/OSG-3.6.5-build --config Release安装目录下会生成bin、lib、include三个子目录。bin里是 DLL 和 exelib里是.lib导入库和.pdb调试符号。注意.pdb要保留好线上崩溃分析靠它了。3.3 验证 OSG 编译结果打开命令行进入安装目录的bin执行osgversion.exe如果输出OpenSceneGraph Library 3.6.5且后面没有报错说明 Release 版可执行文件能正常加载。再执行osgviewer.exe cow.osg这个命令会弹出一个显示奶牛模型的窗口拖动鼠标可以旋转视角。看到窗口就说明核心库和基础插件都正常。4. osgEarth 3.4.0 编译实战4.1 CMake 配置项与依赖绑定osgEarth 的 CMake 配置比 OSG 麻烦一点因为它要显式识别 OSG 的路径。在 CMake GUI 中源码目录选D:/work/src/osgEarth-3.4.0构建目录设为D:/work/build/osgEarth-3.4.0-build。Configure 时同样选 VS 2022 x64。第一次配置后重点检查OSG_DIR是否指向了 OSG 的安装目录。如果 CMake 没有自动找到手动将其设置为D:/work/install/OSG-3.6.5。接着设置这些关键变量变量推荐值说明OSGEARTH_BUILD_SAMPLESON编译示例程序便于验证功能OSGEARTH_BUILD_TESTSOFF测试依赖较多不需要可关掉OSGEARTH_ENABLE_LIBRARYON编译核心库OSGEARTH_USE_OSGXON使用 osgEarth 自带扩展OSGEARTH_USE_QTOFFF如果不需要 Qt 界面则关闭CMAKE_INSTALL_PREFIXD:/work/install/osgEarth-3.4.0安装根目录osgEarth 的第三方依赖比较多GDAL、CURL、GEOS、SQLite3、Protobuf、QThread 都要在 CMake 中显式指定。最省心的方式是预先设置CMAKE_PREFIX_PATH指向D:/work/3rdParty下的各个目录让 CMake 自动搜索cmake -DCMAKE_PREFIX_PATHD:/work/3rdParty/zlib-1.2.13;D:/work/3rdParty/gdal-3.6.3;D:/work/3rdParty/curl-8.0.1;D:/work/3rdParty/geos-3.11.2;D:/work/3rdParty/sqlite3-3.42.0 -DCMAKE_GENERATOR_PLATFORMx64 ..注意CMAKE_PREFIX_PATH里的顺序不影响最终功能但路径一定要指向包含include、lib的目录层级。如果某个库找不到CMake 会在配置界面用红色高亮提示逐个修正即可。4.2 Debug 和 Release 编译以及安装配置生成后同样用命令编译安装cmake --build D:/work/build/osgEarth-3.4.0-build --config Debug --parallel 8 cmake --install D:/work/build/osgEarth-3.4.0-build --config Debug cmake --build D:/work/build/osgEarth-3.4.0-build --config Release --parallel 8 cmake --install D:/work/build/osgEarth-3.4.0-build --config Release这里有个容易踩的坑osgEarth 的 CMake 脚本在生成 VS 工程时会把 Debug 和 Release 的第三方库路径固定成同一个变量。如果你在 Debug 和 Release 下用了不同版本的第三方库切换配置编译时可能会出现“链接到错误库”的问题。建议严格保持同一个库的 Debug 和 Release 版本来自同一套编译产物不要混搭。安装完成后D:/work/install/osgEarth-3.4.0/bin下应该有osgearth_viewer.exe等示例程序。运行osgearth_viewer.exe --earth D:/work/tests/simple.earth准备一个最简单的 earth 文件测试加载map image nameblue marble driverblue-marble urlhttp://server/earth.png/url /image /map如果窗口正常加载出地图贴图说明 osgEarth 核心库、OSG 插件、GDAL/curl 插件都工作正常。如果地图加载不出来看命令行是否有报错通常和 GDAL 驱动、网络代理或 curl 库路径有关。4.3 二进制产物目录结构安装完成后建议把 OSG 和 osgEarth 的bin目录都加入系统 PATH或把 DLL 复制到你的可执行文件目录。我习惯采用后者原因很现实系统 PATH 污染严重时不同版本的 DLL 互相覆盖查问题查得人崩溃。在我的项目目录里依赖 DLL 统一放在depends/子目录下MyApp/ MyApp.exe depends/ osg150-osg.dll osgEarth.dll osgEarthUtil.dll gdal306.dll ...把depends加入 PATH 或使用延迟加载可以让 exe 在启动时找到 DLL同时不影响其他项目。5. 常见问题与排查技巧实录5.1 链接错误RuntimeLibrary 不匹配这个问题出现的频率极高报错信息类似LNK2038 mismatch detected for RuntimeLibrary: value MDd_DynamicRelease doesnt match value MTd_StaticRelease原因很简单你的项目用/MDd的运行时库链接到了用/MTd编译的库上。自编译时要确保 OSG、osgEarth 以及最终应用程序保持一致。我最常用的办法是在每个项目中将“代码生成 运行库”统一为Debug/MDdRelease/MD不要使用/MT或/MTd因为第三方库大多默认以/MD编译混用必然出问题。5.2 运行时缺 DLL 或报 api-ms-win-shcore-scaling 错误如果你把编译好的程序拷到另一台 Windows 10/11 机器上启动时报api-ms-win-shcore-scaling-l1-1-1.dll找不到多半是目标系统缺少 Universal C Runtime 更新。这个问题在 Win7 上尤其明显但在 Win10 老版本上也可能出现。解决思路有两条一是保证目标系统的 Windows Update 已更新到最新二是安装 Visual C Redistributable。另外如果程序在开发机上正常、在别的电脑上报缺 DLL优先检查未使用 /MD 编译导致 VC 运行库没有随程序分发。建议在发布包里带上最新的 VC_redist.x64.exe安装一次就能解决大部分运行库问题。5.3 32 位与 64 位库混用导致崩溃很多同学会忽略进程位数与库位数的匹配。如果你用 x64 编译了你的应用但链接了一个 32 位预编译的 osgEarth 第三方库比如某个老版本的 GDAL运行时往往不会立刻报错而是在调用某个函数时才崩溃非常难排查。排查方法用dumpbin /headers检查每个.lib和.dll的 PE 头确认 machine 类型是x64。也可以在 VS 里打开打开模块窗口看看加载的 DLL 路径是不是预期目录里的那个。不要轻信文件名带不带“64”有些库文件名不带 64 但实际是 64 位。5.4 Debug 版本能编译但 Release 版本报一堆 LNK2001如果 Release 编译时报很多unresolved external symbol先别急着怀疑源码。检查一下链接器“输入 附加依赖项”里是否把所有 Release 库都加进来了。我在 Debug 下习惯用${OSG_LIBRARY_DEBUG}和${OSG_LIBRARY_RELEASE}两组变量但如果只设置了 Debug 变量Release 自然会漏掉。如果懒得手动维护可以直接用 OSG 官方提供的FindOpenSceneGraph.cmake模块它会自动处理 Debug 和 Release 的库名差异。6. 自编译后的项目集成与个人实操心得自编译完成后把 OSG 和 osgEarth 接入自己的项目时CMake 里建议这样写set(OSG_DIR D:/work/install/OSG-3.6.5) set(OSGEARTH_DIR D:/work/install/osgEarth-3.4.0) find_package(OpenSceneGraph REQUIRED COMPONENTS osgDB osgUtil osgViewer) find_package(osgEarth REQUIRED)find_package(osgEarth REQUIRED)依赖OSG_DIR配置所以要先设置OSG_DIR再执行。这样你的项目就能自动引用 Debug 和 Release 库不需要每次改代码。最后说几个我自己的实操心得全是踩坑换来的先编译 Release 再编译 Debug。Release 编译速度快而且很多第三方库的 Release 配置不容易出问题。Debug 编译慢但能帮你筛出一些只有在调试配置下才暴露的库依赖问题。先 Release 后 Debug遇到问题定位更快。所有第三方库严格固定版本不要随意升级。我一开始把 GDAL 换成新版结果 osgEarth 的 GDAL 驱动某个接口签名对不上编译直接 GG。后来把所有库版本锁定半年都没再折腾。保留构建目录和 CMakeCache.txt。如果后续要调整某个编译选项直接在原构建目录里重新 configure 即可千万别删了重建不然又要重新设定几十个变量。每次改动第三方库后务必备份一套编译好的库。我习惯在每个版本的第三方库目录后加版本号比如gdal-3.6.3-ok防止后续手滑覆盖。这套 OSG 3.6.5 osgEarth 3.4.0 的 64 位自编译组合我用了好几个月稳定性让我很放心。如果你也在搞 GIS 可视化或者数字孪生相关项目这套组合完全够用。编译过程中如果再遇到什么“好像只有我遇到”的怪问题欢迎在评论区聊聊说不定我也踩过同一个坑。本文还有配套的精品资源点击获取