VS2019下OSG 3.6.5与OSGEarth预编译3rdParty环境搭建指南

简介：本资源为基于Visual Studio 2019预编译的OSG3.6.5与OSGEarth 2.10配套第三方库，面向从事三维地理可视化、虚拟仿真与数字地球开发的中高级C++工程师，解决自行编译依赖库耗时长、易出错的问题。压缩包共约2000个文件，整体137.76MB，以1351个h头文件、56个lib静态库、32个cmake配置、28个inc及22个c源文件为主，另含少量dll、hpp、proto等，覆盖头文件声明、链接库与构建脚本，可直接接入VS2019工程。目录中附带大量时区与地名数据文件，如Abidjan、Accra、Addis_Ababa、Aden、Alaska等，便于地理坐标与时间系统相关模块的调试。已有626人学习下载，适合需要快速搭建OSG与OSGEarth开发环境、验证三维渲染与地球场景加载的读者，能省去繁琐的依赖编译环节，将精力集中于业务功能开发与效果调优。

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

如果你在 Windows 上从源码编译过 OSG，大概率经历过这样的场景：CMake 配置点下 Generate 的那一刻，满屏红字告诉你 zlib 找不到、libpng 版本不匹配、freetype 链接失败。我前后装过不下十次 OSG 环境，从 OSG 3.4 一路折腾到 3.6.5，最深的体会就是——OSG 本身不难编译，难的是它背后那一长串第三方依赖。尤其是当你还要在上面叠一层 OSGEarth 的时候，GDAL、PROJ、CURL、SQLite3 这些库的版本兼容问题能把人逼疯。所以这篇笔记记录的是我目前最省事的一套方案：直接用预编译好的 3rdParty.zip 三方库，配合 OSG 3.6.5 和 OSGEarth，在 VS2019 下把整套环境跑起来。适合那些不想在依赖编译上耗一整天、只想赶紧把场景跑出来的开发者。

2. 环境准备：VS2019 + CMake + OSG3.6.5 源码与 3rdParty 的版本对齐

2.1 为什么版本对齐比什么都重要

OSG 的第三方库有一个非常要命的特点：它跟编译器版本、运行库模式（MT/MD）、Debug/Release 配置是强绑定的。你拿一个用 VS2017 编译的 3rdParty 去配 VS2019 的工程，链接阶段一定报 LNK2019 或 LNK2038。这不是玄学，是 ABI 不兼容。所以第一步不是急着下载，而是先把版本关系理清楚。

我一般会按下面这张表来核对，缺一项都不往下走：

这里最容易翻车的是 3rdParty 的架构。网上流传的包有的是 Win32 的，有的是 x64 的，混用直接编译不过。我建议统一走 x64，因为现在 GDAL、PROJ 这些库在 x64 下的预编译包更全。

2.2 目录规划：别把源码和依赖搅在一起

我习惯在磁盘根目录建一个干净的工作区，路径里不要有中文和空格，这是血泪经验——CMake 对含空格路径的处理在某些模块上会出问题。结构大概是这样：

D:\OSG_Workspace\ ├── OSG\ # OSG 3.6.5 源码 ├── OSGEarth\ # OSGEarth 源码 ├── 3rdParty\ # 解压后的预编译三方库 │ ├── include\ │ ├── lib\ │ └── bin\ ├── build_osg\ # OSG 的 CMake 构建目录 └── build_osgearth\ # OSGEarth 的 CMake 构建目录

3rdParty.zip 解压后，先确认里面有没有x64子目录。有些包的结构是3rdParty/x64/include，有些是3rdParty/include直接放 64 位库，这两种在 CMake 里填的路径不一样，后面会讲。

2.3 安装 CMake 与确认 VS2019 工具集

CMake 直接去官网下 Windows 的 installer，安装时勾选“Add CMake to the system PATH”。装完在命令行验证：

cmake --version # 输出应为 cmake version 3.20.x 或更高

VS2019 这边要确认安装了“使用 C++ 的桌面开发”工作负载，并且 v142 工具集可用。可以在 VS Installer 里检查，也可以直接看目录：

dir "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\MSVC" # 应能看到类似 14.29.xxxxx 的目录

如果这里只有 14.2 以下的版本，说明 v142 没装全，后面 CMake 生成工程时会找不到编译器。这一步别跳过，我见过太多人卡在这里还以为是 3rdParty 的问题。

3. 编译 OSG 3.6.5：CMake 配置里那几个必须改的变量

3.1 CMake 首次配置与 3rdParty 路径填写

打开 CMake GUI，Source 选D:/OSG_Workspace/OSG，Build 选D:/OSG_Workspace/build_osg。点 Configure，选择 “Visual Studio 2019” 和 “x64”。

第一次 Configure 会报一堆找不到第三方库的错，这是正常的。关键是找到这几个变量并手动指定：

• ACTUAL_3RDPARTY_DIR：指向 3rdParty 的根目录，比如D:/OSG_Workspace/3rdParty
• CMAKE_INSTALL_PREFIX：指向你希望安装 OSG 的位置，比如D:/OSG_Workspace/OSG_Install
• BUILD_OSG_EXAMPLES：建议先关掉，等核心库编译通过再开，能省不少时间

如果 3rdParty 包里是x64子目录结构，ACTUAL_3RDPARTY_DIR要填到3rdParty这一层，CMake 会自动去拼x64/lib。填错的话，zlib、libpng 这些会一直显示 NOTFOUND。

3.2 关键参数取舍：Debug 与 Release 的库路径

OSG 的 CMake 脚本会根据当前配置去 3rdParty 里找对应后缀的库。预编译包里通常长这样：

3rdParty/lib/ ├── zlib.lib ├── zlibd.lib ├── libpng.lib ├── libpngd.lib └── ...

带d后缀的是 Debug 版。如果你只编译 Release，那没问题；但如果要 Debug 和 Release 都出，就得确保两套库都在。我一般会先只编 Release，跑通之后再补 Debug，避免一开始就被一堆 Debug 链接错误劝退。

在 CMake 里还要注意CMAKE_DEBUG_POSTFIX这个变量，OSG 默认给 Debug 库加d后缀，跟 3rdParty 的命名是对应的，不要随意改。

3.3 生成、编译与安装

Configure 没有红色报错之后，点 Generate。然后用管理员权限打开 VS2019 的 x64 命令行，进入 build 目录：

cd D:\OSG_Workspace\build_osg cmake --build . --config Release --target INSTALL

--target INSTALL会直接把编译好的库和头文件复制到CMAKE_INSTALL_PREFIX指定的目录。编译过程大概十几到二十分钟，取决于机器。如果中途报某个 3rdParty 库找不到，回到 CMake 看对应变量是不是 NOTFOUND，手动补上路径再 Generate 一次。

编译完成后，去OSG_Install目录下确认有include、lib、bin三个文件夹。bin里应该有osg165-osg.dll、osgDB165-osg.dll这类文件。版本号 165 对应 OSG 3.6.5，这个数字后面配环境变量要用到。

4. 编译 OSGEarth：依赖 OSG 安装路径与 GDAL/PROJ 的衔接

4.1 让 CMake 找到刚装好的 OSG

OSGEarth 的构建目录单独建一个build_osgearth。Source 选D:/OSG_Workspace/OSGEarth，Build 选D:/OSG_Workspace/build_osgearth。

第一次 Configure 同样会报错，重点是这几个变量：

• OSG_DIR：指向D:/OSG_Workspace/OSG_Install/lib/cmake/osg或者OSG_Install根目录，取决于 OSG 安装时有没有生成 CMake 配置文件
• ACTUAL_3RDPARTY_DIR：跟 OSG 一样，指向同一个 3rdParty
• CMAKE_INSTALL_PREFIX：指向D:/OSG_Workspace/OSGEarth_Install

如果OSG_DIR填对了但 CMake 还是找不到 OSG，检查一下OSG_Install下有没有lib/cmake/osg目录。有些编译方式不会生成这个，那就得手动指定OSG_INCLUDE_DIR和OSG_LIBRARY。

4.2 GDAL 与 PROJ 的版本坑

OSGEarth 对 GDAL 的版本比较敏感。3rdParty 包里带的 GDAL 通常是 3.x 系列，但不同小版本之间 API 有变动。如果编译时报 GDAL 相关的函数找不到，先确认 3rdParty 里的 GDAL 头文件和 lib 是不是同一版本。

常见做法是在 CMake 里显式指定：

GDAL_INCLUDE_DIR = D:/OSG_Workspace/3rdParty/include GDAL_LIBRARY = D:/OSG_Workspace/3rdParty/lib/gdal.lib

PROJ 也是类似，OSGEarth 用它做坐标转换。如果 3rdParty 里 PROJ 的版本太老，可能会在链接阶段报proj_api.h找不到——那是 PROJ 5 以前的头文件，新版已经改成proj.h了。这种情况要么换 3rdParty 包，要么在 CMake 里关掉相关模块。

4.3 编译与安装 OSGEarth

配置通过后，同样用命令行编译：

cd D:\OSG_Workspace\build_osgearth cmake --build . --config Release --target INSTALL

OSGEarth 的编译时间比 OSG 短一些，但依赖 GDAL 的模块会慢。编译完成后，OSGEarth_Install/bin下会有osgEarth.dll、osgEarthUtil.dll等文件。

这里有个细节：OSGEarth 的 DLL 依赖 OSG 的 DLL，所以运行时PATH里必须同时包含 OSG 和 OSGEarth 的 bin 目录，以及 3rdParty 的 bin 目录。少一个就是“找不到 xxx.dll”的弹窗。

5. 避坑与排查：链接错误、DLL 缺失、CMake 缓存这几种翻车

5.1 现象：LNK2038 检测到“RuntimeLibrary”的不匹配

原因：3rdParty 库是用/MD编译的，而你的工程用了/MT，或者反过来。VS 的默认运行库设置和预编译库不一致。

解决：在 CMake 里统一设置CMAKE_MSVC_RUNTIME_LIBRARY为MultiThreadedDLL（对应/MD）。如果 3rdParty 是/MT的，那就改成MultiThreaded。不确定的话，用dumpbin /directives zlib.lib看一下里面的/DEFAULTLIB是MSVCRT还是LIBCMT。

5.2 现象：编译通过，但运行示例程序时弹窗缺osg165-osg.dll

原因：PATH环境变量没配全，或者配了但没生效。

解决：把下面三个路径都加到系统PATH里，然后重启命令行或 IDE：

D:\OSG_Workspace\OSG_Install\bin D:\OSG_Workspace\OSGEarth_Install\bin D:\OSG_Workspace\3rdParty\bin

注意 3rdParty 的 bin 目录可能是在x64/bin下面，别填错层级。

5.3 现象：CMake 反复报同一个变量 NOTFOUND，手动改了下次 Configure 又变回去

原因：CMake 缓存里存了旧值，或者变量名拼写和 CMake 脚本里期望的不一致。

解决：直接删掉 build 目录下的CMakeCache.txt，重新 Configure。我一般遇到诡异问题时第一反应就是删缓存重来，比逐行排查快得多。

5.4 现象：OSGEarth 编译到某个模块时报 GDAL 函数未定义

原因：3rdParty 里的 GDAL 版本和 OSGEarth 源码期望的不一致，通常是 GDAL 3.x 的 API 变动导致。

解决：先确认 3rdParty 里 GDAL 的具体版本，然后去 OSGEarth 的 CMake 选项里找有没有对应的开关。有些模块可以通过-DBUILD_OSGEARTH_GDAL=OFF暂时关掉，先让核心功能跑起来。

5.5 现象：Debug 配置下编译报一堆_ITERATOR_DEBUG_LEVEL不匹配

原因：3rdParty 里只有 Release 版的库，没有 Debug 版，但你在编 Debug。

解决：要么只编 Release，要么找一份带 Debug 库的 3rdParty。预编译包通常 Debug 和 Release 是分开的，下载时看清楚说明。

6. 验证跑通：用 osgViewer 和 osgearth_viewer 确认环境真的能用

装完不验证，等于没装。我一般会走两步：先用 OSG 自带的示例确认核心库没问题，再用 OSGEarth 的示例确认依赖链完整。

6.1 验证 OSG：跑一个最简单的场景

在OSG_Install/bin下应该有osgViewer.exe。准备一个最简单的.osg文件，或者直接用命令行加载一个模型：

cd D:\OSG_Workspace\OSG_Install\bin osgViewer.exe cow.osg

如果弹出一个窗口显示一头牛，说明 OSG 核心库、插件、DLL 路径都没问题。如果报错，重点看弹窗里缺的是哪个 DLL，回到第 5 章排查。

6.2 验证 OSGEarth：加载一个 earth 文件

OSGEarth 的示例程序是osgearth_viewer.exe。它需要一个.earth文件来描述图层。最简单的测试是加载一个本地影像：

cd D:\OSG_Workspace\OSGEarth_Install\bin osgearth_viewer.exe D:\test.earth

test.earth的内容可以极简：

<map name="test"> <image name="world" driver="gdal"> <url>D:\data\world.tif</url> </image> </map>

如果能看到地球影像，说明 GDAL 驱动、PROJ 坐标转换、OSG 渲染管线全部打通。这一步能跑通，整套环境就算真正落地了。

6.3 我自己的验证习惯

从那以后我每次装完 OSG 环境，都会强制走一遍osgViewer加载 cow.osg 和osgearth_viewer加载一个最小 earth 文件的流程。这两个动作花不了两分钟，但能提前暴露 90% 的 DLL 缺失和驱动配置问题。比起在项目里写到一半才发现环境有问题，这个习惯帮我省了太多返工时间。希望这套流程也能帮你顺利把 OSG 3.6.5 和 OSGEarth 跑起来。

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