简介：本资源为基于 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 位、Debug+Release 双配置自编译，这套组合之所以让人反复折腾，核心矛盾在于：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.x，PROJ 用 9.x，CURL 用 8.x，SQLite3 用 3.4x。这些库之间也有依赖：GDAL 3.6+ 依赖 PROJ 9.x，PROJ 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 位 Debug+Release

3.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_PREFIX=D:\dev\OSG\install ^ -DCMAKE_PREFIX_PATH="D:\dev\vcpkg\installed\x64-windows" ^ -DBUILD_SHARED_LIBS=ON ^ -DCMAKE_DEBUG_POSTFIX=d ^ -DCMAKE_RELEASE_POSTFIX= ^ -DBUILD_OSG_APPLICATIONS=ON ^ -DOSG_BUILD_PLUGINS=ON

关键参数说明：-G "Visual Studio 17 2022" -A x64指定 VS2022 和 64 位平台，这是整个编译的基础。CMAKE_DEBUG_POSTFIX=d让 Debug 版本的库文件名带d后缀，比如osgd.lib，这样 Debug 和 Release 的库可以放在同一个目录下而不冲突。BUILD_SHARED_LIBS=ON生成动态库，osgEarth 默认链接动态库，静态库配置起来更麻烦。CMAKE_PREFIX_PATH指向 vcpkg 的安装目录，让 OSG 能找到 zlib、libpng 等依赖。

3.2 编译和安装 OSG

CMake 配置成功后，用以下命令编译并安装：

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.lib

Debug 库带d后缀，Release 库不带。如果只有一种，说明编译配置有问题。另外检查bin目录下是否有对应的 DLL，include目录下是否有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_PREFIX=D:\dev\osgEarth\install ^ -DCMAKE_PREFIX_PATH="D:\dev\OSG\install;D:\dev\vcpkg\installed\x64-windows" ^ -DOSG_DIR=D:\dev\OSG\install\lib\cmake\OpenSceneGraph ^ -DCMAKE_DEBUG_POSTFIX=d ^ -DBUILD_SHARED_LIBS=ON ^ -DOSGEARTH_BUILD_APPLICATIONS=ON ^ -DOSGEARTH_BUILD_TESTS=OFF ^ -DOSGEARTH_BUILD_EXAMPLES=ON

CMAKE_PREFIX_PATH同时包含 OSG 的 install 目录和 vcpkg 的 installed 目录，用分号隔开。OSG_DIR指向 OSG 安装后生成的 CMake 配置文件夹，这个文件夹里有OpenSceneGraphConfig.cmake，osgEarth 通过它找到 OSG 的头文件和库。OSGEARTH_BUILD_TESTS=OFF关掉测试，减少编译时间，除非你需要跑单元测试。

4.2 处理 GDAL 和 PROJ 的路径问题

osgEarth 编译时最常见的报错是找不到 GDAL 或 PROJ。vcpkg 安装的 GDAL 在vcpkg/installed/x64-windows/include/gdal下，但 osgEarth 的 CMake 脚本可能去include根目录找gdal.h。如果报错，手动指定：

-DGDAL_INCLUDE_DIR=D:\dev\vcpkg\installed\x64-windows\include\gdal ^ -DGDAL_LIBRARY=D:\dev\vcpkg\installed\x64-windows\lib\gdal.lib ^ -DGDAL_LIBRARY_DEBUG=D:\dev\vcpkg\installed\x64-windows\debug\lib\gdal.lib ^ -DPROJ_INCLUDE_DIR=D:\dev\vcpkg\installed\x64-windows\include ^ -DPROJ_LIBRARY=D:\dev\vcpkg\installed\x64-windows\lib\proj.lib ^ -DPROJ_LIBRARY_DEBUG=D:\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.dll

4.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_LIB=D:\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 ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003"> <PropertyGroup> <OSG_ROOT>D:\dev\OSG\install</OSG_ROOT> <OSGEARTH_ROOT>D:\dev\osgEarth\install</OSGEARTH_ROOT> <VCPKG_ROOT>D:\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> </Project>

Debug 配置下，链接器输入里加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 的部署清单

把编译好的程序发给别人运行时，需要带上这些 DLL：

另外 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 上做三维地理可视化开发，自己编译一套可控的 Debug+Release 环境，比每次找预编译包靠谱得多。希望帮到你。

本文还有配套的精品资源，点击获取