OSG 3.6.5+OSGEarth 3rdParty 编译配置与避坑

简介：面向 OSG 3.6.5 与 osgEarth 2.10 开发者的第三方依赖库合集，主要解决在 Visual Studio 2019 环境下编译 OpenSceneGraph 与 osgEarth 时依赖缺失、版本不匹配、构建过程冗长的问题。全部依赖均已完成 64 位预编译，下载并解压后即可配置到工程中，省去逐个查找并构建子库的时间。压缩包约含 2000 个文件、137.76MB，以 1351 个 h 头文件为主体，配合 56 个 lib 静态库、4 个 dll 动态库与 32 个 cmake 配置，另有 c、hpp 源码及 inl 内联实现，覆盖头文件、库文件与构建脚本的完整链条；附带的时区描述文件与 tcl、proto 资源也说明其涵盖地理数据与时间处理模块。目前已有 626 人学习下载。对需要快速搭建三维地球渲染与 GIS 可视化原型的中高级开发者，可跳过第三方库编译环节，将精力集中于场景组织、图层加载与坐标调试，并借助 cmake 配置接入 CMake 工程或 VS 属性表，降低环境迁移与协作成本。

1. 版本对不上，编译十次也白搭：OSG 3.6.5 这套 3rdParty 的脾气

A 同学在 VS2019 里配 OSG 3.6.5，CMake 点了几轮 Configure，红色提示停在 zlib 和 png 上；好不容易编过 OSG，接 OSGEarth 又是一堆依赖找不到。这种现场我见过太多次，问题九成不在代码，而在那包预编译的 3rdParty 上——它只认目录层级、位数和运行时库，你把它放错一层，后面全盘皆输。装 OSG 3.6.5 + OSGEarth 最贵的不是编译时间，是反复推倒重来的时间。这篇记录写给已经装到一半、或者准备从头装一遍的人。

2. 目录落位与环境前置：3rdParty 解压到哪、CMake 认哪个层级

预编译三方库最容易踩的地方，不是缺文件，而是「层级放错」。OSG 和 OSGEarth 的 CMake 都通过一个叫ACTUAL_3RDPARTY_DIR的变量去找三方库，这个变量要指向的是包含 bin/lib/include 的那一层，而不是压缩包解出来的最外层。很多人直接指到最外层，CMake 扫一圈什么都没找到，就退化为「找不到系统库」，然后给你一串含义模糊的报错。

2.1 解压后的目录骨架：x64 和 x86 是两个世界

解压完先别急着敲命令，把目录列一遍。常见的预编译包结构大致长这样，具体名字可能有细微差别，但层次是一致的：

# 只看两层，确认 x64 这一层在哪 tree -L 2 /d/3rdParty # 输出大致是： # 3rdParty/ # ├── x64/ # │ ├── bin/ # 运行时 DLL：zlib1.dll、libpng16.dll、gdal303.dll、proj_8_2.dll... # │ ├── include/ # 头文件：zlib.h、png.h、gdal/、proj.h... # │ ├── lib/ # 导入库：zlib.lib、libpng16.lib、gdal_i.lib... # │ └── share/ # 数据文件：gdal/、proj/（不是每个包都有） # └── x86/

bin里放的是运行期 DLL，lib里是链接期用的.lib导入库，include是编译期头文件，三者缺一不可。share目录常被忽略，但 GDAL 和 PROJ 在运行时会依赖里面的数据文件，后面排错那章会专门讲。

注意：如果你的包里 x64 和 x86 混在同一层（bin 里同时有 32 位和 64 位 dll），说明这个包本身整理得比较粗糙，用之前先把 dll 的位数核一遍，否则链接期不报错、运行期直接崩。

VR 里那套「路径写对就行」的直觉在这里不成立。我一般会先做一件事：把ACTUAL_3RDPARTY_DIR候选层级在脑子里固定死——指向3rdParty/x64。因为 VS2019 生成的 x64 工程只认 64 位导入库，指到外层或 x86 层，CMake 可能仍然找到库，但后面链接一定出 LNK1112。

2.2 VS2019 工具集与 CMake 版本核对

OSG 3.6.5 这一代工程，官方脚本和预编译三方库大多是在 MSVC 2015/2017 时代定型的。这里有个好消息：从 VS2015 到 VS2019，微软保持了 MSVC 运行时的二进制兼容，v140/v141/v142 编出来的库可以互相链接，所以用 VS2019（v142）去链预编译的 v141 三方库，通常没有问题。真正会咬人的是运行库选项——/MD、/MDd、/MT必须和预编译库一致，这条后面单独讲。

先确认工具链版本，别在错误的环境里折腾：

:: 必须在 "x64 Native Tools Command Prompt for VS 2019" 里执行 :: 普通 cmd 里敲 cl 会提示找不到命令 cl :: 期望输出：Microsoft (R) C/C++ 优化编译器 版本 19.2x.xxxxx (x64) cmake --version :: 建议 3.20 以上，3.13 起支持 -S / -B 这种写法

cl这一句是分水岭。如果你在普通命令行里敲cl得到「不是内部或外部命令」，说明环境变量没加载，后面无论怎么配 CMake 都会在生成阶段缺编译器。VS2019 安装时勾选「使用 C++ 的桌面开发」和工作负载里的 Windows 10 SDK 就够了，不要额外勾 ARM 或者 UWP 组件，勾多了反而让 CMake 在生成器选择上摇摆。

CMake 的版本也别太低。3.16 以下对多配置生成器支持不够规整，-DCMAKE_CONFIGURATION_TYPES有时候不生效，最后你只编出了一套 Debug 库，Release 链接时找不到osg.lib。

2.3 路径规范：中文、空格、反斜杠三件事

这一条看起来像废话，但每年都有人栽在这里。CMake 的路径解析对反斜杠不友好，D:\3rdParty\x64在命令行里会被当成转义序列吞掉；路径里有中文或者空格，某些老版本 CMake 在写.vcxproj时会把参数截断，表现为「明明填了路径，工程里却是空的」。

统一写成D:/3rdParty/x64这种正斜杠形式，全英文字母，不带空格。我习惯把安装目录规划成下面这样，从第一步就固定死，后面所有配置项都从这里取：

源码目录和编译目录务必分开。有人习惯在源码目录里直接cmake .，结果 CMakeCache.txt 和源码混在一起，换配置时删不干净，第二次编译用到的还是上一次缓存的路径，这种玄学问题排查起来极其难受。删缓存比重装系统还频繁，是我这几年最真实的血泪经验。

3. 编译 OSG 3.6.5：CMake 里那几个必须手填的路径

环境摆好了，进正题。OSG 3.6.5 的 CMake 工程成熟度其实不错，大部分选项保持默认就能过，但如果直接把三方库丢给它「自动探测」，大概率先探到系统里的 Python 或者某个旧版本 zlib，然后告诉你版本不匹配。断掉这个念想，用命令行把路径一次性喂进去。

3.1 一次配置就位：CMake 参数逐条过

先看命令，再看每个参数在干什么：

:: 在源码目录的上一级执行；-S 指源码，-B 指构建目录 cmake -S D:/osg365/src -B D:/osg365/build ^ -G "Visual Studio 16 2019" -A x64 ^ -DACTUAL_3RDPARTY_DIR=D:/3rdParty/x64 ^ -DCMAKE_INSTALL_PREFIX=D:/osg365/install ^ -DCMAKE_CONFIGURATION_TYPES="Debug;Release" ^ -DBUILD_OSG_EXAMPLES=ON ^ -DBUILD_OSG_APPLICATIONS=ON ^ -DBUILD_DOCUMENTATION=OFF

逐条拆开看：

-G "Visual Studio 16 2019" -A x64是生成器与平台。VS2019 的生成器名就是Visual Studio 16 2019，平台必须是x64，不加-A x64默认出 32 位工程，编出来的 exe 一运行就提示不是有效的 Win32 程序。这一对参数要成对出现，只写生成器不写平台，是新手最常见的组合失误。

-DACTUAL_3RDPARTY_DIR是三方库入口，指到x64层。CMake 会据此推导出ZLIB_LIBRARY、PNG_LIBRARY、JPEG_LIBRARY、FREETYPE_LIBRARY、CURL_LIBRARY、GDAL_LIBRARY、PROJ_LIBRARY这一票缓存变量。推荐用 CMake GUI 打开D:/osg365/build后切到 Grouped 视图，展开3rdParty组逐个核对——如果某个变量还是NOTFOUND，说明包里确实没有这个依赖，此时要么补库，要么关掉对应插件。

-DCMAKE_INSTALL_PREFIX是安装位置，注意 install 不是把源码复制过去，而是把编译产物（dll、lib、头文件、osgPlugins 插件目录）按布局摆好，后面 OSGEarth 就是靠这个目录找 OSG。

-DCMAKE_CONFIGURATION_TYPES="Debug;Release"限定多配置生成器的配置集。不写这一条，VS 工程里会多出 RelWithDebInfo、MinSizeRel 两个配置，编译时容易被误选，编出一套没人用的库。

-DBUILD_DOCUMENTATION=OFF纯属省时间。开文档需要 Doxygen，机器上没装的话 CMake 会在生成阶段报错中断，而你其实根本不想要那份 HTML。

提示：配置阶段如果出现Could NOT find ZLIB，不要立刻去改 CMakeLists。先把ACTUAL_3RDPARTY_DIR打印出来确认它指到了x64，再手动设置ZLIB_LIBRARY和ZLIB_INCLUDE_DIR两个缓存变量指向3rdParty/x64/lib/zlib.lib与3rdParty/x64/include。

在 GUI 里手动补路径时，Debug 和 Release 是分开的。ZLIB_LIBRARY是发布版，ZLIB_LIBRARY_DEBUG是调试版，很多预编译三方包只提供了一套发布版.lib（文件名不带d后缀），这时候 Debug 配置下就会在链接期报 LNK1104。做法有两种：一是只编 Release；二是把ZLIB_LIBRARY_DEBUG也指向同一个发布版 lib，能过但调试时看不了三方库内部状态。我一般选前者，除非确实需要进 zlib 或 png 内部排查。

3.2 生成、编译与 install 的落盘位置

配置通过后，编译和安装分两步走。--target INSTALL会触发 install 规则，把产物复制到CMAKE_INSTALL_PREFIX：

:: Release 编一遍并安装 cmake --build D:/osg365/build --config Release --target INSTALL -- /m:8 :: 需要调试版再补一次，不需要可以跳过 cmake --build D:/osg365/build --config Debug --target INSTALL -- /m:8

--config Release指定配置，-- /m:8是透传给 MSBuild 的并行编译开关，8 表示 8 个并行任务。这个数字不要无脑调大：OSG 里有几个源文件（尤其是osgDB下的读写器）单个编译就能吃掉 2GB 以上内存，16 核机器开到/m:16很容易把内存打满然后出现莫名其妙的C1060 堆空间不足。8 核机器上/m:6是比较稳的值，全量 Release 编下来二三十分钟。

如果中途失败，别急着删整个 build 目录，先--target INSTALL再跑一次，增量编译会跳过已完成的目标；只有在 CMake 参数改动过（尤其是三方库路径）时才需要清空重来，因为缓存变量不会自动失效。

注意：--target INSTALL依赖前面的 ALL_BUILD 已经成功。如果你的编译目标是逐个编的，直接跑 INSTALL 只会复制已有产物，缺的 dll 不会自动补。稳妥做法是先cmake --build D:/osg365/build --config Release -- /m:8全量编一遍，再单独跑 INSTALL。

3.3 编译产物自检：四个位置确认装对了

install 跑完，不要立刻去编 OSGEarth。先花两分钟确认 OSG 本体是完整的，否则问题会被推到下一层，排查成本翻倍。

第一看D:/osg365/install/bin，应该同时有osg.dll、osgDB.dll、osgUtil.dll、osgViewer.dll、osgGA.dll、osgText.dll，以及osgPlugins-3.6.5这个子目录。插件目录名带版本号，这是 OSG 的惯例，运行时按版本号去找对应插件，名字对不上就是「插件找不到」。

第二看D:/osg365/install/lib，应该有一整套osg*.lib，以及cmake/osg/目录下的osgConfig.cmake。这个 config 文件是 OSGEarth 的入口，缺了它，OSGEarth 的find_package(OSG)会直接失败。

第三看D:/osg365/install/include/osg，头文件齐全说明 install 规则完整执行了。

第四看osgPlugins-3.6.5里的 dll 数量。如果只有寥寥几个，说明三方库路径没被 CMake 认全，图片格式插件（osgdb_png.dll、osgdb_jpeg.dll）和 GDAL 插件（osgdb_gdal.dll）缺失，后面 OSGEarth 加载影像时会集体罢工。

:: 快速点数：插件目录下应有几十个 dll dir /b D:\osg365\install\bin\osgPlugins-3.6.5\*.dll | find /c /v ""

这一步数出来的数量偏少，就回到 3.1 章，在 CMake GUI 里那堆*_LIBRARY缓存变量上找原因，别往下走。经验上，这一步偷懒省下的十分钟，会在 OSGEarth 那章用两小时还回去。

4. 编译 OSGEarth 并接上运行期依赖

OSGEarth 的编译难度高于 OSG 本体，因为它上面挂的依赖更多：GDAL 管影像读取，PROJ 管坐标系转换，CURL 管网络数据源，SQLite3 管 MBTiles，GEOS 管几何运算。只要有一项路径没接上，CMake 会静默跳过对应功能，编出来的库看起来能用，实际加载某些 earth 文件时才暴露。

4.1 OSG_DIR 与 CMAKE_PREFIX_PATH：让 OSGEarth 找到 OSG

OSGEarth 找 OSG 走的是标准的find_package(OSG)，所以最省事的办法是把两个前缀一起塞进CMAKE_PREFIX_PATH：

cmake -S D:/osg365/earth-src -B D:/osg365/earth-build ^ -G "Visual Studio 16 2019" -A x64 ^ -DCMAKE_PREFIX_PATH="D:/osg365/install;D:/3rdParty/x64" ^ -DOSG_DIR=D:/osg365/install/lib/cmake/osg ^ -DCMAKE_INSTALL_PREFIX=D:/osg365/earth-install ^ -DCMAKE_CONFIGURATION_TYPES="Release" ^ -DBUILD_OSGEARTH_EXAMPLES=ON ^ -DACTUAL_3RDPARTY_DIR=D:/3rdParty/x64

CMAKE_PREFIX_PATH用分号分隔多个前缀，CMake 会依次在<prefix>/lib/cmake/<pkg>、<prefix>/share/cmake/<pkg>下找 config 文件。把D:/osg365/install放前面，是为了优先命中我们自己编的 OSG，而不是系统里可能存在的另一份 OSG。

如果 OSG 不止一份，-DOSG_DIR是更明确的保险。指向的是lib/cmake/osg这个包含osgConfig.cmake的目录，不是install根目录，也不是lib。指错层级的表现是find_package(OSG)返回一堆NOTFOUND，但 CMake 不报错，直到生成阶段才在链接里炸。

-DACTUAL_3RDPARTY_DIR在 OSGEarth 侧同样有效，但它的处理逻辑比 OSG 简单：主要用来定位 GDAL、CURL、PROJ、SQLite3、GEOS。如果这一条没让它自动找齐，就逐个手动补：

-DGDAL_LIBRARY=D:/3rdParty/x64/lib/gdal_i.lib ^ -DGDAL_INCLUDE_DIR=D:/3rdParty/x64/include ^ -DPROJ_LIBRARY=D:/3rdParty/x64/lib/proj.lib ^ -DPROJ_INCLUDE_DIR=D:/3rdParty/x64/include ^ -DCURL_LIBRARY=D:/3rdParty/x64/lib/libcurl.lib ^ -DCURL_INCLUDE_DIR=D:/3rdParty/x64/include ^ -DSQLITE3_LIBRARY=D:/3rdParty/x64/lib/sqlite3.lib ^ -DSQLITE3_INCLUDE_DIR=D:/3rdParty/x64/include

库文件名以你手上的包为准，gdal_i.lib、gdal.lib、libgdal.lib都出现过；PROJ 在 6.0 之后把 API 换过一次，库名也随版本变化，用dir /b D:\3rdParty\x64\lib\*gdal*这种命令先看一眼再填，比照着教程抄更靠谱。

提示：配置完成后，在 CMake GUI 里搜一遍NOTFOUND。GDAL 没找到，OSGEarth 依然能编过，只是osgdb_gdal插件不生成、osgearth_viewer加载 GeoTIFF 时直接报「找不到驱动」。这类静默降级是 OSGEarth 最容易让人误判「装好了」的地方。

4.2 插件裁剪与编译开关：别把能编的都编上

OSGEarth 的 CMake 会把能找到的依赖全部编成插件，依赖越多，编译越慢，出错面也越大。第一次装，我的建议是「先能跑，再补齐」。

-DBUILD_OSGEARTH_EXAMPLES=ON建议开着。里面的osgearth_viewer是最直接的验证工具，比你自己写一个 main 快得多。示例编译失败时，CMake 会一并中断，让你尽早暴露遗漏的依赖。

测试和文档类目标一律关掉。OSGEarth 的测试工程会引入额外依赖，文档目标需要 Doxygen，两者对第一次装环境的人来说都是纯负担。至于 Qt 相关的示例，机器上没有对应版本的 Qt 时 CMake 会自动跳过，不用特意去关，但如果你发现配置阶段卡在 Qt 探测上，手动把相关开关置 OFF 能省几分钟。

Debug 配置在 OSGEarth 侧还有一个隐性成本：三方库大多是 Release 编的，Debug 版 OSGEarth 链接 Release 版 GDAL 时，STL 容器和堆的分配策略不一致，运行期可能出现随机崩溃或者内存泄漏式的增长。所以-DCMAKE_CONFIGURATION_TYPES="Release"这一步直接限定只编 Release，是省掉一整类问题的做法。

编译命令和 OSG 一样：

cmake --build D:/osg365/earth-build --config Release --target INSTALL -- /m:8

OSGEarth 的编译量比 OSG 小不少，8 核机器十几分钟能完。编完检查D:/osg365/earth-install/bin下有没有osgEarth.dll、osgearth_viewer.exe，以及osgEarthUtil.dll、osgEarthAnnotation.dll这些模块。少一个，说明对应的子目录编译被跳过，回头去看 CMake 的输出日志里哪个 target 标了skipped。

4.3 install 之后：PATH、OSG_FILE_PATH、GDAL_DATA、PROJ_LIB

编译完成只是「编过了」，能跑起来还差运行期环境。Windows 下程序找 dll 的顺序是先当前目录、再 PATH，所以下面几个变量必须配：

:: 用管理员权限打开 cmd 执行，setx 写的是用户或系统级持久变量 setx OSG_ROOT "D:\osg365\install" setx PATH "%PATH%;D:\osg365\install\bin;D:\osg365\earth-install\bin;D:\3rdParty\x64\bin" :: 可选：告诉 OSG 去哪里找模型和纹理 setx OSG_FILE_PATH "D:\osg365\install\bin\osgPlugins-3.6.5;D:\osg-data" :: GDAL 与 PROJ 的数据文件，如果压缩包里带 share 目录 setx GDAL_DATA "D:\3rdParty\x64\share\gdal" setx PROJ_LIB "D:\3rdParty\x64\share\proj"

PATH里三个目录缺一不可：install\bin提供 OSG 本体和osgPlugins-3.6.5插件目录，earth-install\bin提供 OSGEarth 的 dll 和 viewer，3rdParty\x64\bin提供 zlib、png、gdal、proj 这些底层依赖。少最后一个的典型症状是程序启动瞬间弹窗「找不到 zlib1.dll」然后退出。

GDAL_DATA和PROJ_LIB是最容易被忽略的两个。GDAL 处理坐标系时要去数据目录找gcs.csv、pcs.csv一类的字典文件，PROJ 需要proj.db做投影转换。这两个变量没设，程序不会启动失败，而是在加载第一个带坐标系的 earth 文件时抛出「Cannot find proj.db」，看起来像代码问题，实际上是环境问题。

注意：setx PATH "%PATH%;..."这种写法有坑。它会把当前会话的 PATH（用户级 + 系统级混在一起）整体写回用户级 PATH，长度超过 1024 字符就会被截断，而且容易写重复。稳妥做法是在「系统属性 → 环境变量」窗口里手动追加，或者用 PowerShell 的[Environment]::SetEnvironmentVariable()只改用户级。这个坑后面还会单独说一次。

配完必须重开一个新的命令行窗口才生效，setx不会影响当前会话。这一点很多人第一次会懵：明明setx提示成功，echo %PATH%里却看不到新增的目录。

5. 排查：从 CMake 报错到运行时崩溃的五类翻车现场

装 OSG 和 OSGEarth 出错的地方高度集中，下面五条是我这边复现率最高的现场，按「现象 → 原因 → 解决」记下来，遇到时照着对照能省掉不少试错。

5.1 链接期报 LNK1112：模块计算机类型 x64 与目标计算机类型 x86 冲突

现象：CMake 配置一路绿灯，编译到链接阶段突然冒出 LNK1112，提示某个.lib的机器类型和目标不一致。

原因：ACTUAL_3RDPARTY_DIR指到了3rdParty根目录，CMake 在根目录下按搜索顺序先摸到了 x86 那一套.lib。也可能是你自己手动填ZLIB_LIBRARY时从 x86 目录里复制的路径。

解决：把ACTUAL_3RDPARTY_DIR明确指到D:/3rdParty/x64，并清空 build 目录重配——缓存变量不会因为你改了外部路径就自动刷新。重配后在 CMake GUI 里逐个确认关键*_LIBRARY都以x64开头。实在不放心，用dumpbin /headers xxx.lib | findstr machine验证一下位数，比猜快。

5.2 Debug 配置下 LNK1104：无法打开文件 zlibd.lib

现象：Release 编得好好的，一换 Debug 就报找不到zlibd.lib、libpng16d.lib这类带d后缀的库。

原因：OSG 的 CMake 在 Debug 配置下会去找带d后缀的调试版三方库，但绝大多数预编译 3rdParty 只提供了一套 Release 库。找不到就直接失败，不是缓存问题。

解决：第一次装就走 Release，把CMAKE_CONFIGURATION_TYPES设成"Release"，从源头上不产生 Debug 目标。确实需要调试 OSG 本体时，把ZLIB_LIBRARY_DEBUG、PNG_LIBRARY_DEBUG这类变量手动指向对应的 Release 版.lib，能链接能跑，代价是进不了三方库内部的调试符号。反过来把 Release 版 dll 硬塞进 Debug 目录更危险，会出现运行期 0xc000007b，那才是真正的黑匣子。

5.3 启动即崩 0xc000007b：位数或运行库不匹配

现象：osgviewer.exe双击闪一下就没，或者直接弹「应用程序无法正常启动 0xc000007b」。

原因有三类。一是 PATH 里混进了 32 位的zlib1.dll，64 位进程加载 32 位 dll 必然失败。二是/MD和/MT混用，OSG 用/MD编，某个三方库是/MT编的，两者同时进一个进程，堆不共享。三是 Debug 版 exe 加载了 Release 版的三方 dll，或者反过来。

解决：先用dumpbin /dependents osgviewer.exe看清它依赖哪些 dll，再用where zlib1.dll确认 PATH 里命中的是哪一个。位数可以用dumpbin /headers或者 Process Explorer 的进程视图看。运行库不一致的典型报错是 LNK2038RuntimeLibrary不匹配，这个在链接期就能看到，好在不用等到运行。

5.4 osgearth_viewer 报 Cannot find proj.db

现象：OSG 侧一切正常，osgviewer能开模型，但osgearth_viewer一加载带坐标系的 earth 文件就抛异常，日志里写着找不到proj.db，或者坐标转换结果全是 NaN。

原因：PROJ 从 6.0 起把坐标系数据从.csv迁到了 SQLite 的proj.db，运行时要靠PROJ_LIB环境变量定位这个文件。变量没设、路径写错、或者预编译包根本就没带share/proj目录，都会触发。

解决：先在3rdParty/x64下找proj.db，dir /s /b proj.db一条命令就能定位。找到后把所在目录设给PROJ_LIB，重开命令行验证。如果包里确实没带，只能从 PROJ 的发行包里单独取一份数据目录，注意版本要和proj.dll对得上，版本错配会直接崩在 SQLite 打开阶段。同理，GDAL_DATA指向的目录里应该有gcs.csv、pcs.csv。

5.5 osgviewer 提示 Could not find plugin to read objects

现象：打开一个.osg或.png纹理时，控制台打出Warning: Could not find plugin to read objects from file xxx.osg，窗口空白。

原因：osgPlugins-3.6.5这个目录没进PATH，或者目录里的插件 dll 位数不对，或者安装时插件根本没生成（三方库没认全，osgdb_png这类读取器被跳过）。

解决：先确认D:\osg365\install\bin\osgPlugins-3.6.5存在且 dll 数量正常，再把它所在的上层bin加进 PATH。OSG 会在 PATH 的每个条目下找名为osgPlugins-<版本>的子目录，所以加bin而不是加插件目录本身。想看得更细，设OSG_NOTIFY_LEVEL=INFO再跑一次，日志会告诉你它到底去哪些路径找过插件，比盲猜快得多。

6. 装完怎么验证跑通：三条命令加一个最小 earth 文件

环境配完，最后一件事是把「装好了」变成「验证过」。我习惯按三步走，从底层往上层递进，每步都有明确的可判定输出，任一步不过就停在那一层排查，不往下走。

osgversion这一条最容易过，但它只能证明 dll 加载没问题，证明不了插件能用。真正有信息量的是osgviewer：能打开模型说明osgDB的插件搜索路径通了，能显示说明 OpenGL 上下文创建成功，能交互说明窗口和事件系统正常。牛模来自 OSG 的示例数据，如果手头没有，用任意.osg或.ive文件替代即可，关键是能读能画。

:: 三个变量一起看，出问题时一眼定位是哪一层 echo %PATH% | findstr /i "osg365 3rdParty" echo %PROJ_LIB% echo %GDAL_DATA%

第三层验证用 OSGEarth 自带的功能比较重，更轻量的办法是写一个最小的 earth 文件，用自己的数据跑一遍。下面这个结构加载一张本地 GeoTIFF 作为底图，是最小可用配置：

<!-- minimal.earth：放在数据同级目录，用 osgearth_viewer minimal.earth 打开 --> <map name="local" type="geocentric" version="2"> <image name="basemap" driver="gdal"> <url>world.tif</url> <cache_policy usage="no_cache"/> </image> <options> <lighting>false</lighting> </options> </map>

type="geocentric"声明球面坐标系，OSGEarth 默认就是这个模式；driver="gdal"要求osgdb_gdal.dll插件在位；<url>是相对路径，相对的是 earth 文件所在目录，写成绝对路径也行但换机器就废；cache_policy usage="no_cache"关掉瓦片缓存，第一次验证时避免缓存目录权限问题混淆判断。打开后能看到一张贴在地球上的影像，说明 GDAL 读取、PROJ 投影、OSG 渲染三层全部打通。

加载失败时先看控制台第一行报错，而不是最后一行。OSGEarth 的日志是层层包裹的，最外层往往只写「failed to load」，真正的原因在最开始那几行，通常是Unable to open ... .tif或者proj.db not found，正好对应前面排查章的两条。

从那以后我每次装完这套环境，都会强制走一遍这三步：先osgversion确认 dll 层，再osgviewer确认插件和渲染层，最后用最小 earth 文件确认 OSGEarth 的影像与坐标系链路。跳过任何一步，后面接项目时都会以更难排查的形式还回来。这套流程不复杂，难的是忍住不跳。希望帮到你。

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