简介：本资源面向使用 MSVC2017 进行三维地理可视化开发的 C++ 工程师与 Qt 桌面应用开发者，提供一套可直接编译运行的 OSG 3.6.3 与 osgEarth 2.10 集成环境，并附带一个简单 Qt 工程示例，帮助读者省去自行编译第三方库的繁琐过程，快速搭建地球场景与三维渲染原型。压缩包约 530MB，共约 2000 个文件，以 hpp 与 h 头文件为主，配合 dll、lib、pdb、ilk 等编译链接产物，另有 earth、shp、tif、osgb 等地理数据与模型资源，以及 frag、vert、lua、qml 等渲染与脚本文件，覆盖开发、调试与运行所需。目前已有 536 人学习下载。借助其中的 Qt 工程与库文件，读者可对照参考文章完成环境配置，理解 OSG 与 osgEarth 的目录组织、依赖关系与调用方式，并在此基础上扩展自己的三维 GIS 应用。

1. 从一次编译翻车说起：msvc2017 + osg3.63 + osgEarth2.10 + Qt5.14 这套组合到底难在哪

有个做三维可视化的朋友在群里发了一张截图，满屏的 LNK2019 和 LNK2001，末尾一行写着无法解析的外部符号。他用的正是 msvc2017 编译 osg3.63，再叠上 osgEarth2.10，最后想塞进 Qt5.14 的 QWidget 里显示。这套组合在桌面端三维 GIS 和仿真项目里太常见了，常见到几乎每个做 OSG 的人都会走一遍，但真正能一次编过的没几个。问题不在某个库本身，而在四者之间的版本咬合：MSVC 的工具集版本、OSG 的第三方依赖、osgEarth 对 GDAL/PROJ 的链接方式、Qt 的构建套件，任何一处对不上，就是几小时的链接报错。这篇笔记按我实际装过的顺序，把环境列清、把编译参数写死、把翻车点标出来，适合第一次搭这套环境的人照着走，也适合被 LNK 折磨过想复盘的人。

2. 装之前先把版本和目录定死：msvc2017 工具集与依赖清单

2.1 为什么是 msvc2017 而不是更新的工具集

osg3.63 和 osgEarth2.10 这两个版本都停留在 2019 年前后，它们的 CMake 脚本里对MSVC_VERSION的判断、对std::filesystem的用法，都是按 VS2017（工具集 v141）写的。如果你用 VS2019 的 v142 或 VS2022 的 v143 去编，大概率会在 osgEarth 的GDAL驱动或PROJ转换那块遇到 C++17 标准差异导致的编译错误。常见做法是：装 Visual Studio 2017，安装时勾选「使用 C++ 的桌面开发」，确保VC\Tools\MSVC\14.16.xxxxx这个目录存在。命令行里用vcvarsall.bat x64初始化环境，后面所有编译都在这个 x64 原生工具命令提示符里做，别用默认的 x86。

:: 在 VS2017 的 x64 Native Tools Command Prompt 里执行 call "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvarsall.bat" x64 cl :: 输出应显示 19.16.xxxxx for x64，确认工具集版本

这段的作用是确认当前 shell 的编译器版本。vcvarsall.bat x64会把cl.exe、link.exe、rc.exe的路径和INCLUDE、LIB环境变量都指向 x64 工具集。如果cl输出的版本不是 19.16 开头，说明你进错了命令行，后面 CMake 生成的工程会混用工具集，链接阶段必炸。

2.2 目录规划：把源码、依赖、安装前缀分开

我一般会建一个根目录，比如D:\dev\osg_stack，下面分四个子目录：src放源码，3rdparty放预编译依赖，build放 CMake 生成物，install放最终安装结果。这样做的原因是 OSG 和 osgEarth 的 CMake 都支持CMAKE_INSTALL_PREFIX，把安装前缀统一到install下，Qt 工程里配置 include 和 lib 路径时只需要指一个根，不用满硬盘找头文件。

第三方依赖这块，OSG 官方推荐用3rdParty预编译包，但那个包比较老，里面的 zlib、libpng 版本和 osgEarth2.10 需要的 GDAL 可能对不上。我的做法是：zlib、libpng、libjpeg、libtiff、freetype 用 vcpkg 装 x64-windows 版本，GDAL 和 PROJ 单独下源码用 msvc2017 编，因为 osgEarth 对 GDAL 的版本敏感，2.10 配 GDAL 2.4.x 比较稳，配 GDAL 3.x 会在OGRFeature接口上报错。

2.3 环境变量与 CMake 生成器的选择

CMake 生成器必须选Visual Studio 15 2017 Win64，不要选 Ninja，除非你确定 Ninja 调用的也是 v141 工具集。在 CMake GUI 里，CMAKE_INSTALL_PREFIX填D:/dev/osg_stack/install，BUILD_MFC_EXAMPLE关掉，BUILD_OSG_EXAMPLES按需开。OSG 的ACTUAL_3RDPARTY_DIR指向3rdparty目录，CMAKE_DEBUG_POSTFIX设成d，这样 debug 版库是osgd.lib，release 版是osg.lib，Qt 工程里切换构建类型时不会混。

:: 在 build\osg 目录下执行 cmake ..\..\src\osg-3.6.3 ^ -G "Visual Studio 15 2017 Win64" ^ -DCMAKE_INSTALL_PREFIX=D:/dev/osg_stack/install ^ -DACTUAL_3RDPARTY_DIR=D:/dev/osg_stack/3rdparty ^ -DCMAKE_DEBUG_POSTFIX=d ^ -DBUILD_MFC_EXAMPLE=OFF

-G指定生成器，^是 Windows 命令行的续行符。CMAKE_DEBUG_POSTFIX=d这个参数很关键，它让 debug 库带d后缀，避免和 release 库同名覆盖。ACTUAL_3RDPARTY_DIR告诉 OSG 去哪里找 zlib、libpng 这些依赖的头文件和 lib。生成完用cmake --build . --config Release --target INSTALL编译并安装，debug 版同理把--config换成Debug。

3. 编译 osg3.63 与 osgEarth2.10：参数怎么填、依赖怎么链

3.1 OSG 3.6.3 的编译与安装

OSG 的编译相对独立，只要第三方依赖找得到，一般能过。但有几个 CMake 选项要手动确认：ZLIB_INCLUDE_DIR、ZLIB_LIBRARY、PNG_LIBRARY、JPEG_LIBRARY这些如果 vcpkg 装好了，CMake 会自动找到；如果找不到，就在 CMake GUI 里手动指到3rdparty对应目录。OSG_USE_UTF8_FILENAMES建议打开，中文路径下加载模型不会乱码。编译时用 Release 和 Debug 各来一遍，因为 Qt 工程调试时需要 debug 版 OSG 库。

:: 编译并安装 Release 版 cmake --build . --config Release --target INSTALL :: 编译并安装 Debug 版 cmake --build . --config Debug --target INSTALL

--target INSTALL会把头文件、lib、dll、可执行文件按CMAKE_INSTALL_PREFIX的目录结构拷过去。装完后install\include\osg下应该有Version.h，install\lib下应该有osg.lib、osgd.lib、osgDB.lib、osgDBd.lib等。如果install\bin下没有 dll，检查 CMake 里的CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS是否被关掉了。

3.2 osgEarth 2.10 对 GDAL 和 PROJ 的链接方式

osgEarth2.10 的 CMake 会去找GDAL和PROJ，它默认用find_package(GDAL)，但 Windows 下 GDAL 的 CMake 配置经常不完整。我一般直接指定GDAL_INCLUDE_DIR和GDAL_LIBRARY，PROJ 同理。GDAL 用 2.4.4 版本，PROJ 用 5.2.0，这两个版本和 osgEarth2.10 的接口匹配。编译 osgEarth 前，确保 OSG 的OSG_DIR指向install\lib\cmake\osg或者手动设OSG_INCLUDE_DIR和OSG_LIBRARY。

cmake ..\..\src\osgearth-2.10 ^ -G "Visual Studio 15 2017 Win64" ^ -DCMAKE_INSTALL_PREFIX=D:/dev/osg_stack/install ^ -DOSG_INCLUDE_DIR=D:/dev/osg_stack/install/include ^ -DOSG_LIBRARY=D:/dev/osg_stack/install/lib/osg.lib ^ -DOSGDB_LIBRARY=D:/dev/osg_stack/install/lib/osgDB.lib ^ -DGDAL_INCLUDE_DIR=D:/dev/osg_stack/3rdparty/gdal/include ^ -DGDAL_LIBRARY=D:/dev/osg_stack/3rdparty/gdal/lib/gdal.lib ^ -DPROJ_INCLUDE_DIR=D:/dev/osg_stack/3rdparty/proj/include ^ -DPROJ_LIBRARY=D:/dev/osg_stack/3rdparty/proj/lib/proj.lib ^ -DCMAKE_DEBUG_POSTFIX=d

这里每个-D都是在补 CMake 自动查找的缺口。OSG_LIBRARY只指了osg.lib，但 osgEarth 还会链osgUtil、osgViewer、osgText，这些 CMake 会通过OSG_LIBRARY所在目录去推，所以install\lib下必须有完整的 OSG 库。GDAL 和 PROJ 的 lib 路径要指到具体文件，不能只给目录，否则 CMake 会报GDAL_LIBRARY is not set。编译时如果遇到PROJ的pj_init_plus找不到，说明 PROJ 版本不对，换 5.2.0 重编。

3.3 把 osgEarth 的插件和数据路径配好

osgEarth 编译完会生成一堆插件 dll，放在install\bin\osgPlugins-3.6.3下。运行时 osgEarth 会去OSG_LIBRARY_PATH或可执行文件同级的osgPlugins目录找这些插件。我一般把install\bin加到系统PATH，然后在 Qt 工程里用osgDB::Registry::instance()->getLibraryFilePathList()把插件路径加进去。数据路径方面，osgEarth 需要osgEarth\resources下的 shader 和纹理，这些在安装时已经拷到install\share\osgearth，代码里用osgEarth::Registry::instance()->getDefaultOptions()时它会自动找。

// Qt 工程初始化时设置 OSG 插件路径 osgDB::Registry* reg = osgDB::Registry::instance(); reg->getLibraryFilePathList().push_back("D:/dev/osg_stack/install/bin/osgPlugins-3.6.3"); // 设置 osgEarth 资源路径 osgEarth::Registry::instance()->setDefaultResourcePath("D:/dev/osg_stack/install/share/osgearth");

这段代码放在main函数里、创建 viewer 之前。getLibraryFilePathList()返回的是一个FilePathList，push 进去的路径会被osgDB::readNodeFile用来找插件。setDefaultResourcePath告诉 osgEarth 去哪里读resources下的文件，不设的话地球加载出来是黑的，因为 shader 没找到。

4. Qt5.14 集成 osgEarth：QWidget 嵌入与构建套件配置

4.1 Qt5.14 的安装与 msvc2017 套件

Qt5.14 在线安装时，组件里要勾MSVC 2017 64-bit，这个套件对应的就是 v141 工具集。装完后在 Qt Creator 的「工具 > 选项 > 构建和运行 > 构建套件」里，确认Desktop Qt 5.14.2 MSVC2017 64bit这个套件存在，编译器选Microsoft Visual C++ Compiler 15.0 (x86_amd64)。如果编译器列表里没有，手动添加，路径指向 VS2017 的VC\Tools\MSVC\14.16.xxxxx\bin\Hostx64\x64\cl.exe。

# Qt 工程 .pro 文件里配置 OSG 和 osgEarth OSG_DIR = D:/dev/osg_stack/install INCLUDEPATH += $$OSG_DIR/include LIBS += -L$$OSG_DIR/lib -losg -losgDB -losgViewer -losgUtil -losgGA -losgText LIBS += -L$$OSG_DIR/lib -losgEarth -losgEarthUtil -losgEarthAnnotation

.pro里LIBS的顺序有讲究，-losgEarth依赖-losg，所以 osgEarth 的库要放在 OSG 库后面。INCLUDEPATH指到install/include，这样#include <osgViewer/Viewer>和#include <osgEarth/MapNode>都能找到。debug 构建时 Qt 会自动加d后缀去找osgd.lib，前提是.pro里没有硬编码库名，用-l让 qmake 自己拼。

4.2 用 QWidget 承载 osgQOpenGLWidget

Qt5.14 集成 OSG 有两种方式：一种是osgQt里的QGLWidget，但那个在 Qt5.14 下已经过时；另一种是用osgQOpenGL库，它提供一个osgQOpenGLWidget，直接继承QOpenGLWidget。osg3.63 的源码里带了osgQOpenGL例子，但没编成库。我一般从 osg 源码的examples\osgQOpenGL里把osgQOpenGLWidget.cpp和头文件拷到工程里，或者单独编一个静态库。

// 在 Qt 窗口里嵌入 osgQOpenGLWidget #include "osgQOpenGLWidget.h" #include <osgViewer/Viewer> #include <osgEarth/MapNode> osgQOpenGLWidget* osgWidget = new osgQOpenGLWidget(this); osgViewer::Viewer* viewer = osgWidget->getOsgViewer(); osg::Node* earth = osgDB::readNodeFile("D:/data/earth.earth"); viewer->setSceneData(earth); viewer->setCameraManipulator(new osgEarth::Util::EarthManipulator()); osgWidget->setGeometry(0, 0, width(), height());

osgQOpenGLWidget构造时会创建QOpenGLContext，getOsgViewer()返回内部的osgViewer::Viewer。setSceneData把 osgEarth 的 earth 文件加载进来，EarthManipulator提供地球的旋转缩放操作。setGeometry让 widget 填满父窗口。如果运行时地球不显示，检查osgQOpenGLWidget的initializeGL是否被调用，有时候需要手动show()一下。

4.3 运行时 dll 的部署与 PATH 设置

Qt 工程编译出的 exe 运行时，需要能找到 OSG、osgEarth、GDAL、PROJ 的 dll。最省事的做法是把install\bin、3rdparty\gdal\bin、3rdparty\proj\bin都加到系统PATH，或者用 Qt 的windeployqt把 Qt 相关 dll 拷到 exe 同级，再手动把 OSG 那堆 dll 也拷过去。我一般写一个deploy.bat，编译完自动拷。

:: deploy.bat 把运行时 dll 拷到输出目录 set OUT=D:\dev\osg_stack\build\myapp\Release copy D:\dev\osg_stack\install\bin\*.dll %OUT% copy D:\dev\osg_stack\3rdparty\gdal\bin\*.dll %OUT% copy D:\dev\osg_stack\3rdparty\proj\bin\*.dll %OUT% xcopy D:\dev\osg_stack\install\bin\osgPlugins-3.6.3 %OUT%\osgPlugins-3.6.3 /E /I

copy把 dll 拷到 exe 同级，xcopy /E /I把插件目录整个拷过去。这样 exe 在没配PATH的机器上也能跑。注意osgPlugins-3.6.3这个目录名要和 OSG 版本一致，osgEarth 读插件时按这个目录名找。

5. 避坑与排查：msvc2017 编译 osgEarth 时最常见的 5 个翻车点

5.1 LNK2019 无法解析的外部符号，指向 GDAL 的 OGRFeature

现象：编译 osgEarth 的OGRFeatureSource时，链接报无法解析的外部符号 "public: virtual __cdecl OGRFeature::~OGRFeature(void)"。原因：GDAL 的 lib 和头文件版本不匹配，或者 GDAL 是用 v142 工具集编的，和当前 v141 的 ABI 不兼容。解决：换 GDAL 2.4.4 源码，用同一个 msvc2017 命令行重新编，编的时候CMAKE_DEBUG_POSTFIX也设成d，确保 debug 和 release 的 lib 都生成。

5.2 运行时地球黑屏，控制台报找不到 shader

现象：Qt 窗口里地球加载出来是纯黑，控制台输出Warning: could not find shader file "skinning.vert"。原因：osgEarth::Registry的默认资源路径没设，或者install\share\osgearth目录没被拷到运行环境。解决：在main里调setDefaultResourcePath，或者把install\share\osgearth整个拷到 exe 同级，osgEarth 会按相对路径找。

5.3 Qt 工程 debug 构建时链接到 release 版 OSG 库

现象：debug 构建的 exe 运行时报MSVCP140.dll版本冲突，或者堆损坏。原因：.pro里LIBS写死了-losg，qmake 在 debug 下没加d后缀，链到了 release 库。解决：.pro里用-losg而不是-losgd，让 qmake 根据CONFIG自动加d；同时确认install\lib下osgd.lib存在。

5.4 osgEarth 编译时 PROJ 的 pj_init_plus 找不到

现象：链接 osgEarth 的SpatialReference时，报无法解析的外部符号 pj_init_plus。原因：PROJ 版本是 6.x 或 7.x，这些版本把pj_init_plus改成了proj_create，接口不兼容。解决：换 PROJ 5.2.0，或者改 osgEarth 源码里的 PROJ 调用，但改源码工作量大，换版本更省事。

5.5 Qt Creator 里构建套件选错导致 CMake 重新生成

现象：在 Qt Creator 里打开 CMake 工程，构建时提示CMAKE_CXX_COMPILER不匹配。原因：Qt Creator 默认用 Ninja 生成器，而之前命令行用的是 VS 生成器，两者工具集不同。解决：在 Qt Creator 的「项目 > 构建设置」里，把 CMake 生成器改成Visual Studio 15 2017 Win64，或者干脆在命令行编好，Qt Creator 只用来写代码和调试。

6. 装完怎么验证：从 osgViewer 到 Qt 窗口的跑通检查

验证这套环境是否真的跑通，不能只看编译过没过，得让地球在 Qt 窗口里转起来。我一般分三步走：先单独跑 OSG 的osgViewer加载一个 cow.osg，确认 OSG 本身没问题；再跑 osgEarth 的osgearth_viewer加载一个 earth 文件，确认 osgEarth 和 GDAL 没问题；最后在 Qt 工程里嵌入osgQOpenGLWidget，确认 Qt 集成没问题。

第一步，命令行跑osgViewer cow.osg。如果窗口弹出来能看到牛，说明 OSG 的 dll、插件、OpenGL 上下文都正常。如果报could not find plugin to read，检查osgPlugins-3.6.3目录是否在PATH或 exe 同级。

第二步，跑osgearth_viewer earth.earth。earth 文件里至少要有image和elevation两层，image 可以指一个本地 tif，elevation 指一个本地 dem。如果地球出来是平的或者黑的，看控制台有没有GDAL相关的报错，通常是 GDAL 数据路径不对或者 PROJ 的proj.db没找到。PROJ 5.2.0 需要proj.db文件，一般在share\proj下，运行时要把这个目录加到PROJ_LIB环境变量。

:: 设置 PROJ 数据路径 set PROJ_LIB=D:\dev\osg_stack\3rdparty\proj\share\proj osgearth_viewer earth.earth

PROJ_LIB指向proj.db所在目录，不设的话 osgEarth 做坐标转换时会报Cannot find proj.db。

第三步，Qt 工程里跑起来后，用osgViewer::Viewer::getCamera()检查getGraphicsContext()是否非空，非空说明 OpenGL 上下文创建成功。再检查viewer->getSceneData()是否非空，非空说明 earth 文件加载成功。最后看帧率，如果帧率是个位数，检查是不是开了OSG_NOTIFY_LEVEL=DEBUG导致日志刷太多，关掉再跑。

从那以后我每次搭这套环境，都会先把vcvarsall.bat x64跑一遍确认工具集，再把PROJ_LIB和OSG_LIBRARY_PATH写进启动脚本，最后用osgearth_viewer加载一个最小 earth 文件做冒烟测试。这套流程走完，Qt 工程里再出问题，基本就是代码层面的，不是环境层面的了。希望帮到你。

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