简介本资源为基于 OpenSceneGraph 3.6.5 自编译的 osgEarth 3.4.0 完整开发包面向在 Windows 平台从事三维地理信息系统开发的 C 工程师尤其适合使用 Visual Studio 2022 进行 64 位项目构建的开发者。资源同时提供 Debug 与 Release 两套配置包含可执行文件、静态库、动态链接库及 pdb 调试信息便于开发阶段定位问题与发布阶段性能优化。压缩包共约 2000 个文件以 1948 个 h 头文件与 47 个 hpp 文件为主另含少量 txt、pdf、c 与 md 文档整体约 483.88MB涵盖 include、lib、bin、cmake 等目录方便直接集成到现有工程。内容涉及 GL2 渲染、地形与纹理处理、地理数据可视化等模块可帮助读者省去繁琐的依赖编译环节快速搭建可调试、可发布的 osgEarth 开发环境。目前已有 1250 人学习下载。1. osgEarth 3.4.0 自编译这件事卡住人的从来不是代码如果你在 VS2022 里拉过 osgEarth 的源码大概率经历过这样的场景CMake 配置点下 Generate红色报错刷满屏幕GDAL 找不到、PROJ 版本对不上、OSG 的 debug 库和 release 库混在一起链接失败。网上能找到的预编译包要么是 OSG 3.4 时代的老古董要么只给 Release 不给 Debug调试时断点根本进不去。osgEarth 3.4.0 搭配 OSG 3.6.5、VS2022、64 位、DebugRelease 双配置自编译这套组合之所以让人反复折腾核心矛盾在于osgEarth 依赖 OSG、GDAL、PROJ、CURL、SQLite3 等一大串第三方库而这些库在 Windows 上几乎没有官方维护的 VS2022 64 位二进制包。你只能自己从源码编或者找到别人编好的、版本严格匹配的库。这篇笔记就把我从零编译这套环境的完整路径拆开包括依赖怎么选、CMake 参数怎么设、Debug 和 Release 怎么共存、以及那些让我重编了三次的坑。2. 编译前的依赖选型为什么 OSG 3.6.5 和 osgEarth 3.4.0 必须锁死版本2.1 OSG 与 osgEarth 的版本对应关系osgEarth 3.4.0 对 OSG 的依赖不是「3.6.x 都行」这么宽松。OSG 3.6.5 是 3.6 系列里比较稳定的一个版本修复了 3.6.3 之前的一些渲染状态泄漏问题同时没有引入 3.7 开发版里的 API 变动。osgEarth 3.4.0 的 CMake 脚本里对 OSG 的最低版本要求写的是 3.6.0但实际编译时如果你用 3.6.0 或 3.6.1会遇到osg::Shader相关接口不匹配的编译错误。我试过 OSG 3.6.3能编过但运行时加载 earth 文件偶尔崩溃换到 3.6.5 后稳定了。第三方库的版本同样敏感。GDAL 建议用 3.6.x 或 3.7.xPROJ 用 9.xCURL 用 8.xSQLite3 用 3.4x。这些库之间也有依赖GDAL 3.6 依赖 PROJ 9.xPROJ 9.x 依赖 SQLite3 和 CURL。如果你从 GDAL 官网下预编译包它自带的 PROJ 版本可能和你想用的不一致导致 osgEarth 在读取投影信息时出错。2.2 用 vcpkg 还是手动编译依赖这是第一个分叉路口。vcpkg 能自动处理依赖关系一条命令装 GDAL、PROJ、CURL省去大量手动配置。但 vcpkg 默认编译的是 Release 版本要同时得到 Debug 和 Release 的库需要分别 install 两次或者用--triplet x64-windows和--triplet x64-windows配合--debug参数。更麻烦的是vcpkg 编译的 OSG 可能不带某些 osgEarth 需要的插件比如 osgdb_earth。我最终选择手动编译 OSG 和 osgEarth第三方库用 vcpkg 装。这样 OSG 和 osgEarth 的 Debug/Release 配置完全可控第三方库的 Debug/Release 由 vcpkg 保证。具体做法是# 安装 vcpkg如果还没装 git clone https://github.com/microsoft/vcpkg.git cd vcpkg .\bootstrap-vcpkg.bat # 安装 64 位 Debug Release 第三方库 .\vcpkg install gdal:x64-windows proj:x64-windows curl:x64-windows sqlite3:x64-windows这里x64-windowstriplet 默认同时编译 Debug 和 Release安装完成后在vcpkg/installed/x64-windows/debug/lib和vcpkg/installed/x64-windows/lib下分别有对应的库文件。注意 vcpkg 的 GDAL 可能默认不带某些驱动如果 osgEarth 需要读取特定格式的影像要在安装时加 feature比如gdal[core,netcdf]:x64-windows。2.3 目录结构规划在动手之前先把目录规划好后面 CMake 配置会清晰很多。我一般这样组织D:\dev\ ├── vcpkg\ # vcpkg 根目录 ├── OSG\ # OSG 源码和编译输出 │ ├── src\ # OpenSceneGraph-3.6.5 源码 │ ├── build\ # CMake 构建目录 │ └── install\ # 安装目录含 include/lib/bin ├── osgEarth\ # osgEarth 源码和编译输出 │ ├── src\ # osgEarth-3.4.0 源码 │ ├── build\ │ └── install\ └── 3rdparty\ # 其他手动编译的依赖OSG 和 osgEarth 的 install 目录分开避免头文件和库文件混在一起。后面在 CMake 里通过CMAKE_PREFIX_PATH同时指向这两个 install 目录和 vcpkg 的 installed 目录。3. 用 CMake 在 VS2022 下编出 OSG 3.6.5 的 64 位 DebugRelease3.1 OSG 源码的 CMake 配置命令OSG 3.6.5 的源码从官网下载后解压到D:\dev\OSG\src。打开 CMake GUI或者直接用命令行。我习惯用命令行方便记录参数cd D:\dev\OSG\build cmake ..\src ^ -G Visual Studio 17 2022 -A x64 ^ -DCMAKE_INSTALL_PREFIXD:\dev\OSG\install ^ -DCMAKE_PREFIX_PATHD:\dev\vcpkg\installed\x64-windows ^ -DBUILD_SHARED_LIBSON ^ -DCMAKE_DEBUG_POSTFIXd ^ -DCMAKE_RELEASE_POSTFIX ^ -DBUILD_OSG_APPLICATIONSON ^ -DOSG_BUILD_PLUGINSON关键参数说明-G Visual Studio 17 2022 -A x64指定 VS2022 和 64 位平台这是整个编译的基础。CMAKE_DEBUG_POSTFIXd让 Debug 版本的库文件名带d后缀比如osgd.lib这样 Debug 和 Release 的库可以放在同一个目录下而不冲突。BUILD_SHARED_LIBSON生成动态库osgEarth 默认链接动态库静态库配置起来更麻烦。CMAKE_PREFIX_PATH指向 vcpkg 的安装目录让 OSG 能找到 zlib、libpng 等依赖。3.2 编译和安装 OSGCMake 配置成功后用以下命令编译并安装cmake --build . --config Debug --target INSTALL -- /m:8 cmake --build . --config Release --target INSTALL -- /m:8-- /m:8是传给 MSBuild 的参数表示用 8 个并行任务编译根据 CPU 核心数调整。先编 Debug 再编 Release因为 Debug 编译时间更长先确保 Debug 没问题。INSTALL 目标会把头文件、库文件、可执行文件复制到CMAKE_INSTALL_PREFIX指定的目录。编译过程中可能遇到的问题如果 vcpkg 的 zlib 是 Debug 和 Release 分开的OSG 的 CMake 脚本可能只找到其中一个。检查CMakeCache.txt里的ZLIB_LIBRARY_DEBUG和ZLIB_LIBRARY_RELEASE是否都正确指向了 vcpkg 的对应路径。如果只找到一个手动在 CMake GUI 里补上另一个。3.3 验证 OSG 安装结果安装完成后检查D:\dev\OSG\install目录# 检查库文件 dir D:\dev\OSG\install\lib\osg*.lib # 应该看到类似 # osg.lib osgd.lib # osgDB.lib osgDBd.lib # osgViewer.lib osgViewerd.lib # osgUtil.lib osgUtild.libDebug 库带d后缀Release 库不带。如果只有一种说明编译配置有问题。另外检查bin目录下是否有对应的 DLLinclude目录下是否有osg文件夹。验证无误后OSG 部分就完成了。4. osgEarth 3.4.0 的 CMake 配置与 Debug/Release 双配置编译4.1 osgEarth 的 CMake 关键参数osgEarth 3.4.0 源码解压到D:\dev\osgEarth\src构建目录D:\dev\osgEarth\build。CMake 命令cd D:\dev\osgEarth\build cmake ..\src ^ -G Visual Studio 17 2022 -A x64 ^ -DCMAKE_INSTALL_PREFIXD:\dev\osgEarth\install ^ -DCMAKE_PREFIX_PATHD:\dev\OSG\install;D:\dev\vcpkg\installed\x64-windows ^ -DOSG_DIRD:\dev\OSG\install\lib\cmake\OpenSceneGraph ^ -DCMAKE_DEBUG_POSTFIXd ^ -DBUILD_SHARED_LIBSON ^ -DOSGEARTH_BUILD_APPLICATIONSON ^ -DOSGEARTH_BUILD_TESTSOFF ^ -DOSGEARTH_BUILD_EXAMPLESONCMAKE_PREFIX_PATH同时包含 OSG 的 install 目录和 vcpkg 的 installed 目录用分号隔开。OSG_DIR指向 OSG 安装后生成的 CMake 配置文件夹这个文件夹里有OpenSceneGraphConfig.cmakeosgEarth 通过它找到 OSG 的头文件和库。OSGEARTH_BUILD_TESTSOFF关掉测试减少编译时间除非你需要跑单元测试。4.2 处理 GDAL 和 PROJ 的路径问题osgEarth 编译时最常见的报错是找不到 GDAL 或 PROJ。vcpkg 安装的 GDAL 在vcpkg/installed/x64-windows/include/gdal下但 osgEarth 的 CMake 脚本可能去include根目录找gdal.h。如果报错手动指定-DGDAL_INCLUDE_DIRD:\dev\vcpkg\installed\x64-windows\include\gdal ^ -DGDAL_LIBRARYD:\dev\vcpkg\installed\x64-windows\lib\gdal.lib ^ -DGDAL_LIBRARY_DEBUGD:\dev\vcpkg\installed\x64-windows\debug\lib\gdal.lib ^ -DPROJ_INCLUDE_DIRD:\dev\vcpkg\installed\x64-windows\include ^ -DPROJ_LIBRARYD:\dev\vcpkg\installed\x64-windows\lib\proj.lib ^ -DPROJ_LIBRARY_DEBUGD:\dev\vcpkg\installed\x64-windows\debug\lib\proj.lib注意 GDAL 的 Debug 和 Release 库文件名可能相同但路径不同。vcpkg 的 Debug 库在debug/lib下Release 库在lib下。如果 CMake 只找到了一个检查CMakeCache.txt里的GDAL_LIBRARY_DEBUG是否为空。4.3 编译 osgEarth 并验证配置成功后编译安装cmake --build . --config Debug --target INSTALL -- /m:8 cmake --build . --config Release --target INSTALL -- /m:8编译 osgEarth 比 OSG 更耗时因为源文件更多而且链接 GDAL 这种大库。如果编译过程中出现链接错误提示找不到osgd.lib或osgDBd.lib检查OSG_DIR是否指向了正确的 CMake 配置目录以及 OSG 的 Debug 库是否确实存在。安装完成后验证D:\dev\osgEarth\install目录dir D:\dev\osgEarth\install\lib\osgEarth*.lib # 应该看到 osgEarth.lib 和 osgEarthd.lib dir D:\dev\osgEarth\install\bin\*.dll # 应该看到 osgEarth.dll 和 osgEarthd.dll4.4 用最小示例验证 Debug 和 Release 都能跑写一个最小的 osgEarth 程序加载一个简单的 earth 文件验证 Debug 和 Release 配置都能正常运行。在 VS2022 里新建一个 C 控制台项目配置包含目录和库目录指向 osgEarth 和 OSG 的 install 目录。#include osgViewer/Viewer #include osgEarth/MapNode #include osgEarth/EarthManipulator #include osgEarth/ExampleResources int main(int argc, char** argv) { osgViewer::Viewer viewer; // 加载示例 earth 文件osgEarth 自带 osg::Node* node osgEarth::Util::ExampleResources::loadEarth( D:/dev/osgEarth/src/tests/simple.earth); if (!node) return -1; viewer.setSceneData(node); viewer.setCameraManipulator(new osgEarth::Util::EarthManipulator()); return viewer.run(); }Debug 配置下链接osgEarthd.lib、osgd.lib、osgDBd.lib、osgViewerd.lib运行时确保PATH包含D:\dev\osgEarth\install\bin和D:\dev\OSG\install\bin。Release 配置下链接不带d的库。如果 Debug 下能跑但 Release 下崩溃检查是否混用了 Debug 和 Release 的 DLL。5. 编译过程中最容易翻车的几个地方5.1 现象CMake 配置时报 “Could NOT find OSG”原因OSG_DIR没有指向 OSG 安装后生成的 CMake 配置目录或者 OSG 安装时没有生成OpenSceneGraphConfig.cmake。解决确认D:\dev\OSG\install\lib\cmake\OpenSceneGraph目录下存在OpenSceneGraphConfig.cmake和OpenSceneGraphConfigVersion.cmake。如果没有说明 OSG 安装不完整重新执行 INSTALL 目标。5.2 现象链接时提示 “无法解析的外部符号 __imp_gdal_XXX”原因GDAL 的 Debug 和 Release 库混用了。osgEarth 的 Debug 配置链接了 Release 的 gdal.lib或者反过来。解决在 CMake 里明确指定GDAL_LIBRARY_DEBUG和GDAL_LIBRARY_RELEASE确保 Debug 配置用debug/lib下的库Release 配置用lib下的库。检查CMakeCache.txt里这两个变量是否都正确。5.3 现象运行时崩溃提示 “无法定位程序输入点于 osg165-osgDB.dll”原因PATH 环境变量里同时存在多个版本的 OSG DLL或者 Debug 程序加载了 Release 的 DLL。解决把D:\dev\OSG\install\bin和D:\dev\osgEarth\install\bin放在 PATH 最前面确保没有其他 OSG 版本干扰。Debug 程序运行时PATH 里应该优先找到带d后缀的 DLL。5.4 现象osgEarth 读取 earth 文件时报 “PROJ: Cannot find proj.db”原因PROJ 9.x 需要proj.db文件来定义坐标系统这个文件在 vcpkg 的share/proj目录下但运行时没有找到。解决设置环境变量PROJ_LIBD:\dev\vcpkg\installed\x64-windows\share\proj或者在程序启动时调用proj_context_set_search_paths指定路径。5.5 现象Debug 编译极慢Release 正常原因Debug 模式下编译器不优化而且 osgEarth 源文件多模板实例化量大。解决这是正常的但可以通过关闭不必要的模块来加速。在 CMake 里把OSGEARTH_BUILD_APPLICATIONS和OSGEARTH_BUILD_EXAMPLES暂时设为 OFF只编译核心库等核心库编译通过后再打开这些选项重新编译。6. 把编译结果用起来VS2022 项目配置与调试技巧6.1 VS2022 项目属性页的配置模板编译完成后在 VS2022 里新建项目使用 osgEarth需要配置几个关键路径。我一般把配置写成一个属性表.props 文件方便多个项目复用。!-- osgEarth.props -- Project ToolsVersion4.0 xmlnshttp://schemas.microsoft.com/developer/msbuild/2003 PropertyGroup OSG_ROOTD:\dev\OSG\install/OSG_ROOT OSGEARTH_ROOTD:\dev\osgEarth\install/OSGEARTH_ROOT VCPKG_ROOTD:\dev\vcpkg\installed\x64-windows/VCPKG_ROOT /PropertyGroup ItemDefinitionGroup ClCompile AdditionalIncludeDirectories $(OSG_ROOT)\include;$(OSGEARTH_ROOT)\include;$(VCPKG_ROOT)\include;%(AdditionalIncludeDirectories) /AdditionalIncludeDirectories /ClCompile Link AdditionalLibraryDirectories $(OSG_ROOT)\lib;$(OSGEARTH_ROOT)\lib;$(VCPKG_ROOT)\lib;%(AdditionalLibraryDirectories) /AdditionalLibraryDirectories /Link /ItemDefinitionGroup /ProjectDebug 配置下链接器输入里加osgEarthd.lib;osgd.lib;osgDBd.lib;osgViewerd.lib;osgUtild.lib;gdal.lib;proj.lib。Release 配置下去掉d后缀。注意 GDAL 和 PROJ 的库名在 Debug 和 Release 下可能相同但路径不同所以库目录要区分。6.2 调试时如何让断点进得去Debug 编译的 osgEarth 库带调试信息但如果你在 VS2022 里调试时断点显示为空心说明符号文件没加载。检查D:\dev\osgEarth\install\bin下是否有osgEarthd.pdb以及 VS2022 的符号路径是否包含这个目录。在「工具」→「选项」→「调试」→「符号」里添加D:\dev\osgEarth\install\bin和D:\dev\OSG\install\bin。6.3 运行时 DLL 的部署清单把编译好的程序发给别人运行时需要带上这些 DLLDLL 名称来源说明osgEarth.dll / osgEarthd.dllosgEarth install/bin核心库osg.dll / osgd.dllOSG install/binOSG 核心osgDB.dll / osgDBd.dllOSG install/bin文件读写osgViewer.dll / osgViewerd.dllOSG install/bin视图器osgUtil.dll / osgUtild.dllOSG install/bin工具库gdal.dllvcpkg installed/binGDAL 运行时proj.dllvcpkg installed/binPROJ 运行时sqlite3.dllvcpkg installed/binSQLite3curl.dllvcpkg installed/binCURL另外 OSG 的插件 DLL 在OSG install/bin/osgPlugins-3.6.5目录下需要整个目录复制。osgEarth 的插件在osgEarth install/bin/osgPlugins-3.4.0下。运行时如果提示找不到某个插件检查这两个目录是否在 PATH 里。6.4 一个我反复用的调试习惯每次重新编译 osgEarth 后我不会直接跑大项目而是先跑一个最小示例加载一个简单的 earth 文件确认渲染正常、坐标投影正确。这个习惯帮我省了很多时间——如果最小示例都跑不起来大项目里排查问题会更痛苦。最小示例的代码就是第 4 章里那段编译成 Debug 和 Release 两个版本分别跑一遍。Debug 下重点看断点能不能进 osgEarth 的源码Release 下重点看性能和稳定性。这个方案值不值得做如果你需要长期在 Windows 上做三维地理可视化开发自己编译一套可控的 DebugRelease 环境比每次找预编译包靠谱得多。希望帮到你。本文还有配套的精品资源点击获取