OSG 3.6.5 + OSGEarth 3.3 预编译3rdParty环境搭建与避坑指南

简介：本资源为基于Visual Studio 2019预编译的OSG3.6.5与OSGEarth 2.10配套第三方库，面向从事三维地理信息、虚拟仿真与三维渲染开发的C++工程师，尤其适合需要快速搭建OSG/OSGEarth编译环境、避免从源码逐个编译依赖库的开发者。压缩包共约2000个文件，整体137.76MB，以1351个h头文件、56个lib静态库、32个cmake配置、28个inc及22个c源文件为主，另含少量dll、hpp、proto等，覆盖头文件声明、链接库与构建脚本，可直接接入VS2019的64位工程。资源内还包含大量时区与地理相关数据文件，便于地理坐标与时间处理场景使用。目前已有626人学习下载，适合希望省去繁琐依赖编译、专注业务逻辑与三维场景开发的中高级开发者参考使用。

1. 从一次编译翻车说起：为什么我最终选了预编译的 3rdParty

如果你在 Windows 上从源码编译过 OSG，大概率经历过这样的场景：CMake 配置顺利通过，Generate 也没报错，结果一按 F7 编译，满屏都是找不到zlib.h、libpng.lib、freetype.dll之类的错误。更让人头疼的是，这些第三方依赖库的版本、编译选项、运行时库（MT/MD）必须和 OSG 主工程完全一致，否则链接阶段就会给你甩出一堆 LNK2019 和 LNK2038。我见过太多人卡在这一步，反复折腾几天甚至一周，最后放弃了 OSG 这条路。

OSG 3.6.5 搭配 OSGEarth 是目前三维地理场景开发中相当成熟的一套组合，VS2019 也是很多团队的主力工具链。但 OSG 本身并不包含第三方依赖，你需要自己准备 zlib、libpng、libjpeg、freetype、GDAL、curl、sqlite3 等一大堆库。这些库如果逐个手动编译，光是版本匹配和编译选项对齐就够喝一壶的。预编译好的 3rdParty.zip 就是来解决这个问题的——它把 OSG 3.6.5 在 VS2019 下需要的第三方库全部编译好、按目录结构打包，解压后直接指定路径就能用。这套方案适合不想在依赖编译上消耗时间、希望快速进入 OSG/OSGEarth 开发正题的开发者，也适合需要统一团队开发环境、避免“我这能编译你那不行”这类扯皮情况的场景。

2. 环境准备：VS2019 与 3rdParty 的版本对齐

2.1 确认 Visual Studio 2019 的安装组件

VS2019 的安装组件选择直接决定了后续能不能顺利编译 OSG。很多人装 VS2019 时只勾了默认的“使用 C++ 的桌面开发”，结果 CMake 配置时找不到 Windows SDK 或者 MSVC 工具集版本不对。我一般会确保以下组件被勾选：

• MSVC v142 - VS 2019 C++ x64/x86 生成工具（这是 VS2019 的默认工具集，版本号 v142）
• Windows 10 SDK（建议选 10.0.17763.0 或更高版本，OSG 3.6.5 对 SDK 版本不挑剔，但太低会缺 API）
• C++ CMake 工具（用于 Windows）（如果你打算用 VS 内置的 CMake 支持）

安装完成后，打开“Developer Command Prompt for VS 2019”，输入cl确认编译器可用。如果提示找不到命令，说明环境变量没配好，需要手动运行vcvarsall.bat x64或者重新安装时勾选“将 MSVC 添加到 PATH”。

提示：VS2019 的版本号（如 16.11.x）不影响 3rdParty 的使用，只要工具集是 v142 即可。但如果你用的是 VS2022（v143），预编译的 3rdParty 里的 .lib 文件可能无法直接链接，需要重新编译或找对应版本。

2.2 3rdParty.zip 的目录结构与版本匹配

拿到 3rdParty.zip 后，先别急着解压到 C 盘根目录。我习惯先看一眼压缩包里的目录结构，确认它是不是按 OSG 官方推荐的布局组织的。典型的预编译 3rdParty 包解压后会长这样：

3rdParty/ ├── bin/ │ ├── x64/ │ │ ├── zlib.dll │ │ ├── libpng16.dll │ │ ├── freetype.dll │ │ └── ... ├── include/ │ ├── zlib.h │ ├── png.h │ ├── freetype/ │ └── ... ├── lib/ │ ├── x64/ │ │ ├── zlib.lib │ │ ├── libpng16.lib │ │ └── ... └── ...

这个结构的关键在于bin/x64、lib/x64和include三个目录。CMake 配置 OSG 时，你需要分别指定ZLIB_INCLUDE_DIR、ZLIB_LIBRARY、PNG_INCLUDE_DIR等变量，而这些变量的值就指向上述目录中的具体文件。

版本匹配方面，OSG 3.6.5 对第三方库的版本要求并不苛刻，但有几个关键点：

如果你拿到的 3rdParty.zip 里包含的版本和上表差异较大，比如 libpng 是 1.4.x，那在 CMake 配置时可能会遇到png_set_longjmp_fn之类的链接错误。这时候要么换一个匹配的 3rdParty 包，要么单独升级那个库。

2.3 解压路径的选择与权限问题

解压路径我建议遵循两个原则：路径中不要有中文和空格，不要放在需要管理员权限才能写入的目录。我一般会解压到D:\dev\3rdParty或者C:\dev\3rdParty。如果你解压到C:\Program Files\下面，后续 CMake 配置时可能因为权限问题无法写入缓存文件，而且某些库在运行时加载 DLL 也会受 UAC 影响。

解压完成后，检查一下bin/x64目录下是否有zlib.dll、libpng16.dll、freetype.dll等文件。如果这些 DLL 缺失，说明压缩包不完整或者解压过程中出了问题。另外，lib/x64目录下应该有对应的.lib文件，这是链接阶段必需的。

注意：有些 3rdParty 包会把 Debug 和 Release 版本的库混在一起，文件名可能带_d后缀。OSG 的 CMake 配置里可以分别指定 Debug 和 Release 的库路径，如果你只做 Release 构建，可以忽略 Debug 版本。

3. 配置 OSG 3.6.5：CMake 参数逐个拆解

3.1 获取 OSG 3.6.5 源码与 CMake 版本要求

OSG 3.6.5 的源码可以从官方仓库获取，下载后解压到一个不含中文和空格的路径，比如D:\dev\OpenSceneGraph-3.6.5。CMake 版本建议用 3.20 以上，VS2019 自带的 CMake 版本通常够用，但如果你单独安装 CMake，记得把cmake命令加到 PATH。

我一般会在源码目录外新建一个build目录，比如D:\dev\osg-build，然后在 build 目录里执行 CMake 配置。这样做的好处是源码目录保持干净，重新配置时直接删掉 build 目录就行，不用重新解压源码。

# 在 build 目录下执行，假设源码在 D:/dev/OpenSceneGraph-3.6.5 cmake -G "Visual Studio 16 2019" -A x64 ^ -DCMAKE_INSTALL_PREFIX=D:/dev/osg-install ^ -DACTUAL_3RDPARTY_DIR=D:/dev/3rdParty ^ -DBUILD_OSG_APPLICATIONS=ON ^ -DBUILD_OSG_EXAMPLES=OFF ^ D:/dev/OpenSceneGraph-3.6.5

这段命令里几个关键参数的含义：

• -G "Visual Studio 16 2019"：指定生成 VS2019 的工程文件，16是 VS2019 的内部版本号。
• -A x64：指定目标平台为 64 位。如果你的 3rdParty 是 32 位的，这里要改成Win32。
• -DCMAKE_INSTALL_PREFIX：指定install目标的安装路径，编译完成后执行cmake --install .会把头文件、库文件和可执行文件复制到这里。
• -DACTUAL_3RDPARTY_DIR：这是 OSG 的 CMake 脚本里用来定位第三方库的变量，指向你解压的 3rdParty 根目录。
• -DBUILD_OSG_APPLICATIONS=ON：编译 osgViewer、osgconv 等实用工具，建议开启。
• -DBUILD_OSG_EXAMPLES=OFF：示例程序编译很耗时，而且容易因为缺少数据文件而失败，非必要不开。

3.2 手动指定第三方库路径的常见场景

有时候ACTUAL_3RDPARTY_DIR并不能让 CMake 自动找到所有库，尤其是当 3rdParty 包的目录结构和 OSG 预期的不完全一致时。这时候你需要手动指定几个关键变量。我遇到最多的情况是 freetype 和 libpng 找不到，CMake 会报Could NOT find PNG或Could NOT find Freetype。

手动指定的方式是在 CMake 命令里追加以下参数：

-DPNG_INCLUDE_DIR=D:/dev/3rdParty/include ^ -DPNG_LIBRARY=D:/dev/3rdParty/lib/x64/libpng16.lib ^ -DPNG_PNG_INCLUDE_DIR=D:/dev/3rdParty/include ^ -DFREETYPE_INCLUDE_DIRS=D:/dev/3rdParty/include/freetype2 ^ -DFREETYPE_LIBRARY=D:/dev/3rdParty/lib/x64/freetype.lib ^ -DZLIB_INCLUDE_DIR=D:/dev/3rdParty/include ^ -DZLIB_LIBRARY=D:/dev/3rdParty/lib/x64/zlib.lib ^ -DJPEG_INCLUDE_DIR=D:/dev/3rdParty/include ^ -DJPEG_LIBRARY=D:/dev/3rdParty/lib/x64/libjpeg.lib

这些变量的命名规则来自 CMake 的FindPNG.cmake、FindFreetype.cmake等模块。注意FREETYPE_INCLUDE_DIRS指向的是include/freetype2而不是include，因为 freetype 的头文件通常放在freetype2/freetype/下面。如果你指向了错误的目录，编译时会报ft2build.h找不到。

提示：CMake 配置完成后，仔细看输出日志里有没有Could NOT find的字样。如果有，说明某个库没被正确识别，需要手动补上对应的变量。不要忽略这些警告，它们就是后面编译报错的根源。

3.3 生成工程与编译安装

CMake 配置成功后，会在 build 目录下生成OpenSceneGraph.sln。用 VS2019 打开这个解决方案，选择Release和x64，然后右键ALL_BUILD选择生成。编译过程大概需要 20 到 40 分钟，取决于机器性能。

编译完成后，右键INSTALL项目选择生成，这会把所有产物复制到CMAKE_INSTALL_PREFIX指定的目录。安装完成后，检查D:/dev/osg-install下是否有bin、include、lib三个目录。bin目录里应该有osgViewer.exe、osgconv.exe等工具，lib目录里应该有osg.lib、osgDB.lib、osgUtil.lib等。

如果你在编译过程中遇到LNK2038错误，提示RuntimeLibrary不匹配，说明 3rdParty 里的库和 OSG 主工程的运行时库选项不一致。OSG 默认使用MultiThreadedDLL（即/MD），如果你的 3rdParty 是用/MT编译的，就会冲突。解决办法是在 CMake 里设置-DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreadedDLL，或者重新找一个匹配的 3rdParty 包。

4. 编译 OSGEarth：依赖 GDAL 与 curl 的额外配置

4.1 OSGEarth 版本选择与源码获取

OSGEarth 的版本需要和 OSG 3.6.5 匹配。目前比较稳定的组合是 OSGEarth 3.2 或 3.3，这两个版本都支持 OSG 3.6.x。下载源码后解压到D:\dev\osgearth-3.3，同样在外部新建 build 目录。

OSGEarth 的 CMake 配置比 OSG 多几个依赖项，最关键的是 GDAL 和 curl。如果你的 3rdParty 包里已经包含了这两个库，配置会顺利很多；如果没有，你需要单独准备。GDAL 用于读取地理空间数据格式（如 GeoTIFF、Shapefile），curl 用于网络数据加载。这两个库在 OSGEarth 里都是强依赖，缺一不可。

4.2 CMake 配置 OSGEarth 的关键参数

OSGEarth 的 CMake 配置命令和 OSG 类似，但需要额外指定 OSG 的安装路径和 GDAL/curl 的路径：

cmake -G "Visual Studio 16 2019" -A x64 ^ -DCMAKE_INSTALL_PREFIX=D:/dev/osgearth-install ^ -DOSG_DIR=D:/dev/osg-install ^ -DACTUAL_3RDPARTY_DIR=D:/dev/3rdParty ^ -DGDAL_INCLUDE_DIR=D:/dev/3rdParty/include ^ -DGDAL_LIBRARY=D:/dev/3rdParty/lib/x64/gdal.lib ^ -DCURL_INCLUDE_DIR=D:/dev/3rdParty/include ^ -DCURL_LIBRARY=D:/dev/3rdParty/lib/x64/libcurl.lib ^ -DBUILD_OSGEARTH_EXAMPLES=OFF ^ D:/dev/osgearth-3.3

这里OSG_DIR指向 OSG 的安装目录，CMake 会从这里找osg-config.cmake或OpenSceneGraphConfig.cmake。如果找不到，可以手动指定OSG_INCLUDE_DIR和OSG_LIBRARY。

GDAL_LIBRARY和CURL_LIBRARY的命名可能因 3rdParty 包而异，有的叫gdal.lib，有的叫gdal_i.lib。你需要在lib/x64目录下确认实际文件名。如果 CMake 报Could NOT find GDAL，先检查GDAL_INCLUDE_DIR下是否有gdal.h，再检查GDAL_LIBRARY指向的文件是否存在。

4.3 编译过程中的典型报错与处理

OSGEarth 编译时最常见的报错是fatal error C1083: 无法打开包括文件: "gdal.h"。这通常是因为GDAL_INCLUDE_DIR指向了错误的层级。GDAL 的头文件一般在include/gdal/下面，但有些包会直接放在include/下。你需要根据实际情况调整路径，或者在 CMake 里追加-DGDAL_INCLUDE_DIR=D:/dev/3rdParty/include/gdal。

另一个常见问题是 curl 的链接错误，提示unresolved external symbol __imp__curl_easy_init。这说明CURL_LIBRARY指向的.lib文件不对，可能是 Debug 版本或者静态库版本。OSGEarth 需要的是 Release 版本的动态库导入库（.lib），对应的 DLL 是libcurl.dll。确认lib/x64下有libcurl.lib和bin/x64下有libcurl.dll。

如果编译到一半报LNK1181: 无法打开输入文件 "osgEarth.lib"，说明 OSGEarth 的某个子项目依赖另一个子项目的输出，但编译顺序不对。这种情况在 VS 里重新生成整个解决方案通常能解决，因为 VS 会自动处理项目依赖关系。

5. 避坑记录：装 3rdParty 时最容易翻车的五个点

5.1 现象：CMake 配置通过，但编译时报大量 LNK2019

原因：3rdParty 里的.lib文件和 OSG 主工程的运行时库选项不一致。最常见的是 3rdParty 用/MT编译，而 OSG 默认用/MD。/MT是静态链接 CRT，/MD是动态链接 CRT，两者不能混用。

解决：在 CMake 配置时显式指定-DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreadedDLL，强制 OSG 使用/MD。如果 3rdParty 确实是/MT的，那就需要重新编译 3rdParty 或者找/MD版本的包。判断方法是用dumpbin /directives zlib.lib查看里面的/DEFAULTLIB指令。

5.2 现象：运行时提示找不到 zlib.dll 或 libpng16.dll

原因：编译时链接了.lib，但运行时需要对应的.dll。这些 DLL 在 3rdParty 的bin/x64目录下，但系统 PATH 里没有这个目录。

解决：把D:/dev/3rdParty/bin/x64加到系统 PATH 环境变量里，或者把需要的 DLL 复制到你的可执行文件所在目录。我一般会在开发机上直接把 3rdParty 的 bin 目录加到 PATH，这样所有项目都能用。注意修改 PATH 后需要重启命令行或 VS 才能生效。

5.3 现象：OSGEarth 编译时找不到 gdal.h

原因：GDAL 的头文件路径层级和 CMake 预期的不一致。有些 3rdParty 包把gdal.h放在include/下，有些放在include/gdal/下。

解决：先确认gdal.h的实际位置，然后调整GDAL_INCLUDE_DIR。如果gdal.h在include/gdal/下，就设-DGDAL_INCLUDE_DIR=D:/dev/3rdParty/include/gdal。如果 CMake 仍然找不到，可以尝试设置环境变量GDAL_INCLUDE_DIR或者在 CMake GUI 里手动指定。

5.4 现象：编译到 90% 时报错，提示某个 .lib 文件损坏或格式不对

原因：3rdParty 包在下载或解压过程中损坏，或者压缩包本身就不完整。这种情况在从某些网盘下载大文件时比较常见。

解决：重新下载并解压，解压时关闭杀毒软件（有些杀毒软件会误删.lib文件）。解压后可以用dumpbin /headers xxx.lib检查文件是否有效。如果某个库反复出问题，可以单独从其他来源获取那个库的预编译版本。

5.5 现象：Debug 配置下编译失败，Release 正常

原因：3rdParty 包里只有 Release 版本的库，没有 Debug 版本（文件名通常带_d后缀）。OSG 的 CMake 配置里可以分别指定 Debug 和 Release 的库路径，如果 Debug 路径为空，就会去链接 Release 库，导致运行时库不匹配。

解决：如果你只做 Release 开发，直接在 VS 里选 Release 配置编译即可。如果需要 Debug 版本，要么找包含 Debug 库的 3rdParty 包，要么在 CMake 里把 Debug 和 Release 的库路径都指向 Release 版本（不推荐，但能编译通过）。我一般建议团队统一用 Release 配置开发，避免 Debug/Release 混用带来的各种玄学问题。

6. 验证安装：用 osgViewer 和 osgearth_viewer 跑通第一个场景

装完 OSG 和 OSGEarth 之后，别急着写代码，先用官方工具验证一下环境是否真的可用。这一步能帮你排除掉大部分配置问题，避免在写业务代码时才发现环境有坑。

首先验证 OSG。打开命令行，把D:/dev/osg-install/bin加到 PATH，然后运行：

osgViewer cow.osg

如果弹出一个窗口显示一头牛，说明 OSG 的渲染管线、插件加载、DLL 依赖都没问题。如果报错Could not find plugin to read objects from file "cow.osg"，说明osgPlugins目录没被正确识别。OSG 默认会在可执行文件同级的osgPlugins-3.6.5目录下找插件，确认这个目录存在且包含osgdb_osg.dll等文件。

接下来验证 OSGEarth。运行：

osgearth_viewer earthfile.earth

如果你没有现成的.earth文件，可以用 OSGEarth 自带的示例数据。在 OSGEarth 源码的tests目录下有一些简单的 earth 文件，复制一个到命令行所在目录，然后运行。如果能看到一个三维地球，说明 GDAL、curl、OSG 的集成都没问题。

提示：如果osgearth_viewer启动后闪退，大概率是某个 DLL 缺失。用 Dependencies 工具（或 VS 的“模块”窗口）查看它加载了哪些 DLL，对比 3rdParty 的 bin 目录，缺哪个补哪个。

最后，我习惯再做一个编译层面的验证：新建一个空的 C++ 项目，写几行代码调用 OSG 和 OSGEarth 的 API，确认头文件和库都能正确引用。

// test_osgearth.cpp #include <osgViewer/Viewer> #include <osgEarth/MapNode> int main() { osgViewer::Viewer viewer; // 创建一个最简单的 MapNode，验证 OSGEarth 链接正常 osg::ref_ptr<osgEarth::MapNode> mapNode = new osgEarth::MapNode(); viewer.setSceneData(mapNode); return viewer.run(); }

在 VS 里配置好包含目录（osg-install/include、osgearth-install/include）和库目录（osg-install/lib、osgearth-install/lib），链接osg.lib、osgViewer.lib、osgEarth.lib等。如果编译链接通过并能运行，说明整套环境已经完全就绪。

从那以后，我每次配完 OSG 环境都会强制走一遍osgViewer cow.osg和osgearth_viewer这两个验证步骤，确认没问题再开始写业务代码。这个习惯帮我省下了大量“以为是代码问题、其实是环境问题”的排查时间。希望帮到你。

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