用了一周时间终于把 Windows 上的 OSG 3.6.5、OSGEarth 3.7.2、GDAL 3.12 这套组合给全部编译通了。说实话这套东西单个拿出来编译都不算难难的是把它们串在一起。OSGEarth 对版本敏感GDAL 又有一堆可选依赖OSG 的插件机制在 Windows 上还特别容易出问题。我把整个过程中踩过的坑、验证过的配置、走了弯路之后确定的最终方案全部记录下来给后面要搞这套环境的兄弟一个可以直接照抄的参考。先说下为什么选这几个版本。OSG 3.6.5 是目前 3.6 系列里比较稳定的一个版本社区里用的人多遇到问题比较容易搜到解决方案OSGEarth 3.7.2 支持较新的 OSG 接口特性又是 3.x 里相对成熟的GDAL 3.12 是当前的功能重头戏对各类遥感影像、矢量格式的支持都比较全。这套组合在三维 GIS 项目里是常见的生产配置。这里我编译的环境是Windows 11 专业版 Visual Studio 2022v143 工具集 CMake 3.29.3。VS2022 的 v143 工具集向下兼容v120、v140所以即使你项目工程还在用老一点的编译器标准这套依赖库也不会冲突。1. 项目整体设计与编译顺序这一节先讲清整体思路。整个编译链条有严格的依赖关系GDAL 在最底层OSG 在中间OSGEarth 在最上层。OSG 本身不依赖 GDAL但 OSGEarth 需要同时找到 OSG 和 GDAL并且它编译时需要用到 GDAL 的头文件和库文件来解析地理数据。所以无论你之前是否已经装过 OSG只要打算编译 OSGEarth就必须先把 GDAL 搞定。1.1 编译顺序为什么必须是 GDAL → OSG → OSGEarth先编译 GDAL是因为 OSGEarth 的 CMake 配置阶段会通过find_package(GDAL)来查找 GDAL如果此时 GDAL 还没编译安装配置就会直接报错。而且 GDAL 的安装路径要在 OSGEarth 配置时能被正确找到这就涉及环境变量和 CMake 搜索路径的设置必须提前规划好。OSG 放在 GDAL 之后是因为 OSG 编译过程相对独立不涉及 GDAL但 OSGEarth 在配置时需要同时指定 OSG 的路径。OSG 自身有两个关键构建产物OpenThreads库线程抽象层和osgDB插件加载器这两个库在 OSGEarth 编译时都会被引用。1.2 目录规划编译这种依赖链很长的项目目录规划非常重要。建议把所有源码和编译产物集中在一个根目录下后续排查问题时能省大量时间。我的目录结构如下D:\3rdparty\ ├── src\ │ ├── gdal-3.12.0\ │ ├── OpenSceneGraph-3.6.5\ │ └── osgearth-3.7.2\ ├── build\ │ ├── gdal\ │ ├── osg\ │ └── osgearth\ └── install\ ├── gdal\ ├── osg\ └── osgearth\源码目录、构建目录、安装目录完全分离。构建目录独立出来非常关键一旦 CMake 配置出问题直接删掉 build 目录重来不需要碰源码特别适合反复试错的场景。1.3 Release/Debug 编译策略这是很多人容易踩坑的地方。GDAL、OSG、OSGEarth 三者的运行时库必须一致也就是说要编译 Debug 就全部编译 Debug要编译 Release 就全部编译 Release。原因很简单三者之间存在跨模块的指针传递和 STL 容器交互Debug 和 Release 的运行时库不同MD vs MDd混用会导致内存释放崩溃甚至编译报错。我这次编译了 Release 版本在整个开发周期内统一使用 Release 模式。如果调试需要建议单独编译一套 Debug 版本不要混着用。2. 环境准备与工具链配置编译这套东西工具链准备不充分会非常痛苦。下面详细说下我这边验证过的版本组合。2.1 Visual Studio 版本选择VS2022 是最稳妥的选择。VS2019 也能编译但在 OSGEarth 3.7.2 的某些版本里C17 标准在 v142 工具集下会有细微差异增加排查成本。VS2022 默认支持 C17且 v143 工具集对 CMake 生成的解决方案兼容性更好这是效率优先的选择。需要重点确认的是安装 VS2022 时是否勾选了“使用 C 的桌面开发”工作负载。这个工作负载包含 MSVC 编译器、Windows SDK、CMake 工具等默认情况下 CMake 和 Ninja 也会一并安装。如果没有勾选后面 CMake 生成时会提示找不到编译器那时候再补装也不是不行但比较费时间。2.2 CMake 版本要求GDAL 3.12 要求 CMake 3.16 以上OSGEarth 3.7.2 要求 3.10 以上OSG 3.6.5 要求 2.8 以上实际建议更高。我用的 CMake 3.29.3一次过了三个项目没有任何版本瓶颈。Windows 下 CMake 安装没什么好说的直接去官网下载 Windows x64 Installer安装时选择“Add CMake to the system PATH for all users”方便命令行直接调用。如果你是命令行控用 Visual Studio 自带的 Developer PowerShell 也可以。2.3 依赖库获取策略vcpkg 还是源码编译这是每个玩 Windows 编译的人都要做的选择题。vcpkg 的好处是包管理简单vcpkg install gdal一行命令就完成了依赖解析和编译。但坏处也很明显vcpkg 编译出来的库默认是带 vcpkg 的 toolchain 信息的OSGEarth 的 CMake 在查找 GDAL 时有时候会产生路径解析问题尤其是CMAKE_TOOLCHAIN_FILE和你自己的 CMake 配置混在一起时特别容易出古怪问题。我这次选择了全部源码编译原因是这套环境是给长期项目用的稳定性优先。GDAL 的源码洗一遍能保证所有的第三方依赖如 GEOS、PROJ、SQLite 等都是自己可控的后续维护时思路清晰。如果你只是临时搭个环境学习vcpkg 会快很多但出问题的概率也相对高。2.4 环境变量规划在开始编译之前先把环境变量规划好。我设置了两个用户级环境变量GDAL_HOME D:\3rdparty\install\gdal OSG_ROOT D:\3rdparty\install\osg这三个库的安装目录统一在D:\3rdparty\install下。因为 OSG 的 CMake 配置文件会以OSG_ROOT或 CMake 的CMAKE_PREFIX_PATH来搜索设置好这个变量可以在编译 OSGEarth 时少配置很多参数。提示设置完环境变量后需要重新打开终端或直接重启 VS让环境变量生效。3. GDAL 3.12 编译实操GDAL 是这个链路里第一个要啃的硬骨头。虽然它本身的编译不算复杂但它依赖的若干库会让你感受到“依赖地狱”的滋味。3.1 源码下载与目录准备去 GDAL 官网或者 GitHub Releases 页面下载gdal-3.12.0.tar.gz解压到D:\3rdparty\src\gdal-3.12.0。GDAL 源码包内自带了一部分第三方的头文件比如 sqlite3但在 Windows 上如果要用到完整功能还是建议准备以下常用依赖PROJ坐标系转换必须GDAL 3.12 强制要求 PROJ 6 以上版本SQLite3很多矢量格式和内部元数据管理要用GEOS空间拓扑运算如果只做影像读写可以不要Curl读取在线地图服务、WMS 时会用到如果这些依赖没安装GDAL 的 CMake 配置会自动禁用相关功能但这样编译出来的 GDAL 性能和作用大打折扣后面 OSGEarth 加载某些功能时也可能缺能力。所以该装的还是装齐。我这里采用的是提前用 vcpkg 编译 PROJ、SQLite3、Curl、GEOS然后把它们的头文件和库路径传给 GDAL 的 CMake 配置。对 GDAL 来说它不关心这些依赖是怎么来的只要能找到头文件和库文件就行。注意如果依赖库是自己源码编译的请确保和 GDAL 使用的运行时库一致MD/MDd否则后面链接阶段会出现 LNK2038 之类的运行时库不匹配错误。3.2 CMake 配置关键选项GDAL 从 3.x 开始推荐使用 CMake 构建系统替代传统的 configure 脚本。在D:\3rdparty\build\gdal目录下执行cmake ..\..\src\gdal-3.12.0 -G Visual Studio 17 2022 -A x64 \ -DCMAKE_INSTALL_PREFIXD:/3rdparty/install/gdal \ -DCMAKE_BUILD_TYPERelease \ -DGDAL_BUILD_SHARED_LIBON \ -DGDAL_USE_EXTERNAL_LIBSOFF关键参数解释-DGDAL_BUILD_SHARED_LIBON生成 DLL 动态链接库。OSGEarth 链接 GDAL 时最好用动态库静态库会导致整个依赖链变得极其复杂而且多个模块内嵌 GDAL 静态副本还会有符号重复的问题。-DGDAL_USE_EXTERNAL_LIBSOFF这个参数让 GDAL 优先使用系统外部库而不是自带的内部库副本。如果你已经手动编译了 PROJ 等依赖这个选项能保证 GDAL 链接的是你编译的版本避免内部副本和外部库混用导致的两个版本共存冲突。CMake configure 完成之后检查输出的摘要信息。重点确认以下几行PROJ 库是否被找到SQLite3 是否可用Curl 是否被启用共享库是否开启如果发现某些库没找到回到你的依赖库路径检查或者用-DPROJ_INCLUDE_DIR、-DPROJ_LIBRARY这类变量手动指定路径。3.3 编译与安装CMake 配置通过后直接编译cmake --build . --config Release --parallel 8 cmake --install .--parallel 8是用 8 个线程并行编译根据自己的 CPU 核心数调整。GDAL 的完整编译在 8 核机器上大约需要 15-25 分钟取决于开关了多少功能。编译过程中最常见的报错来自 PROJ 版本不匹配。GDAL 3.12 对 PROJ 有版本号检查如果 PROJ 版本太老会直接报Cannot find PROJ 6.0之类的错误。这时候要么降级 GDAL 版本要么升级 PROJ我这边用的是 PROJ 9.x编译顺利通过。安装完成后验证一下D:\3rdparty\install\gdal\bin\gdalinfo.exe --version如果能正常输出版本信息说明 GDAL 动态库、路径和依赖都正常。3.4 踩坑记录DLL 路径与依赖GDAL 编译通过只是第一步真正折磨人的是运行时 DLL 找不到。GDAL 的 bin 目录下有gdalinfo.exe但它依赖的 PROJ DLL、Curl DLL 等都在各自的安装目录里。解决方案有两个一是把依赖库的 DLL 全部复制到 GDAL 的 bin 目录下二是把依赖库的 bin 目录加入 PATH。我采用后者因为后续 OSGEarth 运行时也会用到这些库。实际操作中我把D:\3rdparty\install\gdal\bin、PROJ 的 bin、SQLite3 的 bin、Curl 的 bin 全部加进了系统 PATH这样整个依赖链的 DLL 查找路径就全覆盖了。重要Windows 下 DLL 搜索顺序是先找应用程序所在目录再找 PATH 中的目录。如果 GDAL 的 bin 目录同时包含gdal.dll和proj.dll那依赖库全部放到这个目录下是最保险的做法。4. OSG 3.6.5 编译实操OSG 编译相对 GDAL 来说清爽一些但它的插件体系在 Windows 上需要额外注意。OSG 是通过插件Plugin的形式加载不同格式的模型和图片的编译完成后如果没有对应插件哪怕主体库编译成功了实际用起来还是寸步难行。4.1 依赖库检查OSG 3.6.5 需要的核心依赖包括OpenGLWindows SDK 自带不需要额外安装zlib处理压缩数据推荐提前编译好libpng / libjpeg / libtiff读图片格式OSG 的纹理加载必须freetype字体渲染处理文字节点的时候必须curl读取网络资源、远程模型时使用giflibGIF 文件读取可选但建议加上如果这些库全部缺失OSG 也能编译成功但只支持 osg 自带的三维模型格式那这套环境就没有实用价值了。尤其 libpng 和 libjpeg没有它们整个节点的纹理加载都会失败场景一片空白。我这边使用 vcpkg 安装了 zlib、libpng、libjpeg、libtiff、freetype、curl。安装路径是 vcpkg 默认的C:\vcpkg\installed\x64-windows编译 OSG 时手动指定路径。4.2 CMake 配置核心参数在D:\3rdparty\build\osg目录下执行cmake ..\..\src\OpenSceneGraph-3.6.5 -G Visual Studio 17 2022 -A x64 \ -DCMAKE_INSTALL_PREFIXD:/3rdparty/install/osg \ -DCMAKE_BUILD_TYPERelease \ -DZLIB_INCLUDE_DIRC:/vcpkg/installed/x64-windows/include \ -DZLIB_LIBRARYC:/vcpkg/installed/x64-windows/lib/zlib.lib \ -DPNG_INCLUDE_DIRC:/vcpkg/installed/x64-windows/include \ -DPNG_LIBRARYC:/vcpkg/installed/x64-windows/lib/libpng16.lib \ -DJPEG_INCLUDE_DIRC:/vcpkg/installed/x64-windows/include \ -DJPEG_LIBRARYC:/vcpkg/installed/x64-windows/lib/jpeg.lib \ -DTIFF_INCLUDE_DIRC:/vcpkg/installed/x64-windows/include \ -DTIFF_LIBRARYC:/vcpkg/installed/x64-windows/lib/tiff.lib \ -DCURL_INCLUDE_DIRC:/vcpkg/installed/x64-windows/include \ -DCURL_LIBRARYC:/vcpkg/installed/x64-windows/lib/curl.lib \ -DCURL_DLLC:/vcpkg/installed/x64-windows/bin/curl.dll \ -DOSG_USE_QTOFF这里重点解释几个-DOSG_USE_QTOFF如果你的机器没装 Qt或者不想让 OSG 跟 Qt 绑在一起这个一定要置为 OFF否则 CMake 会去寻找 Qt 库找不到就容易报错。-DCMAKE_BUILD_TYPERelease虽然是 VS 多配置生成器会忽略这个变量但设置清楚总没错。-DOSG_BUILD_APPLICATIONSON默认 ON会编译 osgviewer、osgconv 等命令行工具这些工具在验证环境时非常有用。配置完成后检查 CMake 输出中的第三库部分确认 png、jpeg、tiff、zlib 都已经找到状态应为build或1。4.3 编译过程中的常见错误OSG 编译过程中我遇到的第一个报错是Cannot open include file: png.h: No such file or directory。原因是 PNG 的头文件路径没有正确传给 CMake或者 vcpkg 工具的路径下有多个 PNG 头文件版本。解决办法是检查PNG_INCLUDE_DIR是否指向了包含png.h的目录。第二个报错是编译 osgdb_tga 插件时提示找不到 OpenGL 的某个函数定义。这个一般是由于 Windows SDK 版本太低导致的。VS2022 自带的 Windows 10/11 SDK 已经完全兼容 OSG 3.6.5如果出现这个问题检查你的 Windows SDK 版本号在 VS Installer 里升级到最新版即可。第三个报错比较隐蔽LNK2019: unresolved external symbol __imp__curl_easy一般是 Curl 的库路径指定错误。OSG 在 Windows 下链接 Curl 时才用的是curl.lib但 vcpkg 的库文件可能在libcurl.lib目录下注意确认实际文件名。4.4 编译与插件验证配置通过后执行cmake --build . --config Release --parallel 8 cmake --install .编译不会太长8 核大约 10 分钟就能完成。编译结束后去D:\3rdparty\install\osg\bin目录看看bin\ ├── OpenThreads.dll ├── osg.dll ├── osgDB.dll ├── osgUtil.dll ├── osgViewer.dll ├── osgGA.dll ├── osgText.dll ├── osgPlugins-3.6.5\ │ ├── osgdb_png.dll │ ├── osgdb_jpeg.dll │ ├── osgdb_tiff.dll │ ├── osgdb_osg.dll │ ├── osgdb_ive.dll │ └── ...osgPlugins-3.6.5目录里必须能看到常见格式的插件 DLL比如 png、jpeg、tiff、osg、ive、stl、obj 等。我这次只装了上述几个依赖库所以插件目录里大概有 20 多个 DLL。验证是否编译成功可以用 osgviewer 打开一个模型文件D:\3rdparty\install\osg\bin\osgviewer.exe D:\3rdparty\src\OpenSceneGraph-3.6.5\examples\osglogo\osglogo.osg如果能看到 OpenSceneGraph 的 logo 模型说明 OSG 主体库和插件加载都没问题。这里还有个重要的环境变量OSG_FILE_PATH和插件路径变量OSG_LIBRARY_PATH。OSG 默认会在可执行文件同目录下的osgPlugins-3.6.5文件夹中找插件。如果你把 osgviewer.exe 复制到了别的目录插件就找不到了。所以要么把插件目录和 exe 放一起要么设置OSG_LIBRARY_PATH D:\3rdparty\install\osg\bin\osgPlugins-3.6.55. OSGEarth 3.7.2 编译实操终于到了最复杂的部分。OSGEarth 的编译在配置阶段就需要同时找到 OSG 和 GDAL并且要确保版本符合要求。这里我再强调一次OSG 和 GDAL 都编译安装完成后再开始配置 OSGEarth否则 CMake 会直接失败浪费你排查时间。5.1 前置依赖确认除了 OSG 和 GDAL 之外OSGEarth 还建议准备以下库protobuf某些版本用于高程服务的数据交换格式支持curl加载 Web 地图服务tinyxmlXML 解析部分 Earth 文件功能用如果你的应用不涉及这些高级功能可以先不装。但 curl 建议装因为在线地图服务和 WMS 是 OSGEarth 的核心能力之一。如果缺 curlOSGEarth 在运行时加载远程地图会出现加载失败的提示。5.2 CMake 配置难点正确找到 OSG 和 GDAL这是整个过程中最容易出问题的环节。OSGEarth 的 CMake 使用find_package(OSG)和find_package(GDAL)来查找依赖。find_package(OSG)会去找 OSG 的 CMake 配置文件OSGConfig.cmake而 OSG 的 CMake 配置文件在安装后位于D:\3rdparty\install\osg\lib\cmake\osg目录下。如果 CMake 找不到 OSG先检查OSG_ROOT环境变量是否已经设置。或者直接在 CMake 配置时指定cmake ..\..\src\osgearth-3.7.2 -G Visual Studio 17 2022 -A x64 \ -DCMAKE_INSTALL_PREFIXD:/3rdparty/install/osgearth \ -DCMAKE_BUILD_TYPERelease \ -DCMAKE_PREFIX_PATHD:/3rdparty/install/osg;D:/3rdparty/install/gdal \ -DOSGEARTH_USE_QTOFF \ -DOSGEARTH_USE_OSGQOFF \ -DOSGEARTH_USE_BULLETOFF解释几个关键点-DCMAKE_PREFIX_PATH这是解决搜索问题的万能钥匙。你可以指定多个路径用分号隔开。CMake 会在这些路径下寻找所有的*-config.cmake文件。我这里把 OSG 和 GDAL 的安装路径都写在里面三个项目一次找到。-DOSGEARTH_USE_QTOFF如果不需要 Qt 集成关掉它避免 CMake 在 Qt 上耗时间。-DOSGEARTH_USE_BULLETOFF物理引擎一般不需要。配置完成后检查 CMake 的 summary 输出确认以下内容OSG 路径已找到且版本 3.6.0GDAL 路径已找到且版本 3.0.0Curl 路径如果启用Protobuf 路径如果启用常见报错是Could NOT find OSG (missing: OSG_INCLUDE_DIR OSGDB_LIBRARY)这种一般是OSG_ROOT没设置或 CMake 缓存还残留着上次查找的路径。解决方法是删掉 build 目录重新配置不要试图在一个已经失败的缓存里改来改去。5.3 编译与链接问题排查配置通过后执行编译cmake --build . --config Release --parallel 8OSGEarth 编译大约 5-10 分钟。这个阶段最让人崩溃的是链接错误。我遇到的第一个链接错误是LNK1104: cannot open file osgViewer.lib。排查后发现原因在于 OSG 安装时没有把osgViewer.lib这类文件导出到 lib 目录。实际上 OSG 的安装目录只有bin和include在 CMake 配置时指定给 OSGEarth 的库路径必须是D:\3rdparty\install\osg\lib。但我的安装路径下没有生成 lib 目录原因是 OSG 安装时默认不导出库文件。解决办法是回到 OSG 的 CMake 配置勾选OSG_INSTALL_CMAKE_FILES和OSG_INSTALL_LIBRARIES或者直接指定-DOSG_INSTALL_LIBRARIESON重新编译安装 OSGlib 目录下就会出现所有需要的 .lib 文件。第二个链接错误是unresolved external symbol __imp__gdalsetconfigoption之类的。这个是因为 OSGEarth 链接 GDAL 库时没有正确找到 GDAL 的导入库。检查你的D:\3rdparty\install\gdal\lib目录确保存在gdal.lib。如果存在但还是报错需要在 CMake 缓存中手动确认GDAL_LIBRARY变量是否指向了正确的 .lib 文件。有时候 CMake 会找到了一些其他项目里的旧 GDAL 库。5.4 编译产物验证编译安装完成后OSGEarth 的 bin 目录下应该有以下关键文件bin\ ├── osgEarth.dll ├── osgEarthUtil.dll ├── osgEarthFeatures.dll ├── osgEarthSymbology.dll ├── osgEarthAnnotation.dll ├── osgEarthQt.dll如果启用 Qt ├── osgearth_viewer.exe ├── osgearth_cache.exe ├── osgearth_manip.exe └── ...还可以写一个最简单的 earth 文件来验证map nameSimpleDemo version2 options lightingfalse/lighting /options image layer drivergdal urlD:/testdata/world.tif/url /image /map然后执行D:\3rdparty\install\osgearth\bin\osgearth_viewer.exe D:\testdata\simple.earth如果窗口能打开并显示影像说明 OSG、GDAL、OSGEarth 三个库已经协同工作了。6. 运行环境配置与测试验证编译完成后还有一个容易被忽视的关键环节运行环境的配置。很多人在编译阶段折腾了半天最后跑不起来八成就是 DLL 加载路径的问题。6.1 PATH 环境变量设置我把以下目录全部加进了系统 PATHD:\3rdparty\install\gdal\bin D:\3rdparty\install\osg\bin D:\3rdparty\install\osg\bin\osgPlugins-3.6.5 D:\3rdparty\install\osgearth\bin C:\vcpkg\installed\x64-windows\bin如果依赖通过 vcpkg 安装注意OSG 插件目录本身也需要加入 PATH 吗严格来说 OSG 会在程序运行时通过OSG_LIBRARY_PATH变量去查找插件目录而不是通过 PATH。但加入 PATH 没有副作用可以作为一种后备方案。所以除了 PATH还需要设置OSG_LIBRARY_PATH D:\3rdparty\install\osg\bin\osgPlugins-3.6.5 OSG_FILE_PATH D:\3rdparty\install\osg\dataOSG_FILE_PATH指向 OSG 自带的数据目录里面有些模型和贴图调试程序时可以直接用相对路径引用。6.2 插件加载验证OSG 的插件加载机制是动态的这意味着出问题时不会在编译阶段报错而是在程序运行到加载模型或纹理的瞬间才报Could not find plugin to read objects from file。排查这个问题的方法osgviewer.exe D:\testdata\test.osgb如果提示找不到对应的 reader检查插件目录下是否有osgdb_osgb.dll。如果插件 DLL 存在但仍然报错用 Dependency Walker 或/DEPENDENTS命令行检查插件 DLL 的依赖很可能是插件 DLL 依赖了某个第三方 DLL比如 libpng.dll但是系统 PATH 里找不到。另外一个常见问题是插件版本不匹配。OSG 的插件 DLL 名称带有版本号比如osgdb_png.dll而 OSGEarth 在运行时会请求特定版本的插件。确保osgPlugins-3.6.5目录内的插件版本和 OSG 主库版本一致不要把多个版本的插件混在一起。6.3 最小化测试示例这里分享一个我实际项目中用来验证环境完整性的最小测试流程检查 GDAL 读取影像gdalinfo.exe D:\testdata\world.tif检查 OSG 加载模型osgviewer.exe D:\testdata\terrain.osgb检查 OSGEarth 加载 earth 文件osgearth_viewer.exe D:\testdata\simple.earth如果三步都能通过这套环境基本就稳了。我这边在实际项目里用这套环境跑了地形渲染、卫星影像叠加、矢量标注等功能稳定性和性能表现都能达到预期。7. 常见问题与排查技巧整理最后把整个编译过程中遇到的高频问题整理成表格方便你在碰到同样问题时直接对照排查。这些问题每一个我都在实际项目中踩过。问题现象可能原因解决办法GDAL configure 时找不到 PROJPROJ 版本过老或未安装重新编译 PROJ 9.x并用-DPROJ_INCLUDE_DIR和-DPROJ_LIBRARY指定路径GDAL 编译报错 C1083 缺少 sqlite3.hSQLite 依赖未安装在 CMake 配置中指定-DSQLite3_INCLUDE_DIR和-DSQLite3_LIBRARY或通过 vcpkg 安装OSG 编译时提示找不到 libpngPNG include 路径错误在 CMake 配置时显式指定PNG_INCLUDE_DIR不要依赖自动查找OSG 编译后缺少 osgPlugins 目录安装步骤没有正确执行确认cmake --install .成功且安装目录下有 bin/osgPlugins-3.6.5OSGEarth CMake 找不到 OSGCMake 缓存问题或 OSG_ROOT 未设置设置 OSG_ROOT 环境变量删除 build 目录重新 configureOSGEarth 链接时找不到 OSG 的 .lib 文件OSG 安装时未导出库文件重新配置 OSG开启 OSG_INSTALL_LIBRARIESON重新编译安装运行 osgearth_viewer 时提示缺 gdal.dllGDAL 的 bin 目录未加入 PATH把 GDAL、PROJ、Curl 的 bin 目录加入系统 PATH运行 osgearth_viewer 时提示找不到插件插件目录没有正确设置设置 OSG_LIBRARY_PATH 指向 osgPlugins-3.6.5 目录模型中纹理全是黑色libpng/libjpeg 插件缺失检查 osgPlugins 目录下是否有对应的 osgdb_png.dll 和 osgdb_jpeg.dllDebug 和 Release 库混用导致崩溃三个库的运行时库不一致全部使用同一个配置Release 或 Debug重新编译编译链接时出现 LNK2038 运行时库不匹配依赖库使用 MDd 而主库使用 MD或反之统一依赖库的CMAKE_MSVC_RUNTIME_LIBRARY设置再补充几个不那么明显但实际很重要的经验第一CMake 缓存问题。每一次修改 CMake 配置前最好把 build 目录下的CMakeCache.txt删掉或者整个 build 目录删掉重来。CMake 一旦在缓存里记录了某个错误的路径你后面怎么传参数它都不会变因为缓存的优先级高于命令行参数。这是我踩过最多次的坑。第二保持编译器一致性。GDAL、OSG、OSGEarth 都必须用同一个 VS 版本和同一个编译器工具集编译。我见过有人用 VS2019 编译 GDAL用 VS2022 编译 OSG最后 OSGEarth 链接时一堆奇怪的符号错误。跨编译器工具集编译出来的 C 库是不能混用的因为 name mangling 和内存布局都有差异。第三静态库还是动态库。我强烈建议这套环境里的所有库都用动态库。原因有两点一是 OSG 的插件机制要求插件 DLL 与主程序使用相同的内存管理方式动态库能保证这点二是动态库方便更新改一个库不需要重新链接整个应用。第四备份编译产物。编译一次这么长的依赖链很耗时建议在确认环境稳定后把D:\3rdparty\install目录整体打包备份再写一份说明文档记录每个库的 CMake 配置参数。这样即使后续系统挂掉或者需要换机器也能快速恢复环境。8. 结语与个人心得编译这套环境的过程中我最大的体会是Windows 上源码编译最大的敌人不是代码本身而是依赖管理。GDAL 要 PROJPROJ 还要依赖 SQLite 和 CurlOSG 又要 zlib/libpng/libjpeg这些库的版本组合稍有差池就会满盘皆输。所以想给后面动手的兄弟们一条最核心的建议别贪多别求全按需开启功能把不需要的依赖全部关掉。GDAL 的很多可选功能如果你用不到直接关闭可以减少一半的编译时间OSG 的 Qt 接口如果不需要也别开。这套环境的成功关键是让链路上每个环节都简单可控而不是追求功能大而全。再分享一个最终的小技巧编译完成后建议用dumpbin /dependents命令检查关键 DLL 的依赖关系。比如osgEarth.dll到底依赖了哪些 DLL、路径是否正确这个工具能让你在问题出现之前就发现问题。我整个排查过程中通过这个命令快速定位了至少三个 DLL 缺失问题比靠猜快多了。这套编译环境到我截稿时已经在项目上稳定运行了三周加载了约 20GB 的遥感影像数据做过坐标转换、地形分析、矢量编辑等操作没有出现过编译或运行层面的问题。希望这次编译记录能帮到你祝编译顺利。