简介面向在 Visual Studio 2019 下构建 OSG 3.6.5 与 OSGEarth 2.10 的图形开发者这份预编译三方库合集主要解决依赖库自行编译耗时、版本不匹配、链接失败等问题适合具备一定 C 与 CMake 基础、从事三维地球可视化或 GIS 引擎开发的中高级读者。压缩包为 64 位版本约 2000 个文件、137.76MB1351 个头文件与 56 个 lib 导入库构成声明与链接主体另有 32 个 cmake 配置、28 个 inc、22 个 C 源文件及 inl、proto、hpp 等辅助内容并附少量 dll 与 html 说明。目前已有 626 人学习下载。解压后可直接在工程中设置包含目录与附加依赖项省去从源码逐个编译 GDAL、PROJ、zlib 等依赖的重复劳动把精力放在场景组织与图层加载上目录保留原始层级便于按模块定位缺失组件也可作为团队统一的依赖基线减少协作中的版本漂移。1. OSG3.6.5 装到 VS2019 前先把 3rdParty 的版本对齐OSG3.6.5 和 OSGEarth 在 VS2019 下的安装最容易翻车的部分往往不是编译命令而是预编译 3rdParty.zip 与生成器、架构、Debug/Release 没对齐。很多人拿到三方库就解压CMake 也能跑最后却卡在 LNK2019 或缺 DLL。这个场景在三维渲染、地理信息可视化项目里很常见尤其是需要快速复现一套能跑的环境。3rdParty 不是解压完就万事大吉它要和 OSG3.6.5、OSGEarth、VS2019 的 x64/Win32、v142 工具集、运行库逐项对上。刚接手 OSG 环境、不想从 zlib 开始逐个编依赖的开发者适合按下面的顺序走一遍。2. 环境清单与目录规划OSG 3.6.5 OSGEarth VS2019 的安装前准备预编译 3rdParty 的价值在于省掉 zlib、libpng、jpeg、curl、GDAL 这类依赖的源码编译但它只解决“库从哪来”不解决“怎么接进工程”。我一般先把目录固定下来再动 CMake。目录里不要出现中文、空格和过长的路径后面 CMake 缓存、链接器附加依赖项、运行时 DLL 搜索都会少很多玄学问题。2.1 先定工具链VS2019 生成器、x64 和 CMakeVS2019 对应的 CMake 生成器是Visual Studio 16 2019架构通过-A x64或-A Win32指定。3rdParty 里的.lib是 64 位还是 32 位必须先确认如果库是 x64OSG 和 OSGEarth 也必须用 x64不能只改生成器不改架构。我习惯在 VS2019 的 Developer PowerShell 里操作这样cl、dumpbin、cmake都在 PATH 里排查时不用来回切终端。# 在 VS2019 Developer PowerShell 中确认工具链可见 cmake --version where.exe cl where.exe dumpbincmake --version只用来确认当前终端能找到 CMakewhere.exe cl和where.exe dumpbin用来确认 VS2019 的编译器与二进制检查工具已经进入当前会话。如果cl找不到不要急着配系统环境变量先换到 Developer PowerShell 再执行很多“CMake 找不到编译器”的问题其实是终端开错了。2.2 解压 3rdParty.zip先看 lib 和 bin不要急着配环境变量预编译三方库常见目录是include、lib、bin有的包还会带share或按 Debug/Release 再分层。先看lib下的文件名和后缀确认是x64还是Win32确认 Debug 库是否带d后缀。不要看到zlib.lib就直接往链接器里塞先确认它和当前生成器架构一致。# 查看三方库根目录结构 Get-ChildItem D:\dev\osg365\3rdParty | Select-Object Name, Mode # 取一个 lib 检查机器类型需在 VS2019 Developer PowerShell 中执行 $lib Get-ChildItem D:\dev\osg365\3rdParty\lib\*.lib | Select-Object -First 1 dumpbin /headers $lib.FullName | Select-String machinedumpbin /headers输出里的machine (x64)或machine (x86)就是架构信息。这个检查比“看目录名猜架构”可靠。若输出x86而 CMake 用了-A x64后面大概率会在链接阶段报模块机器类型冲突没必要等到那时候再回头查。注意3rdParty 里的库不一定全部由同一个运行库选项编译。若你的工程用/MT而三方库是/MD即使架构对了也可能出现 LNK2038。最省事的做法是让 OSG、OSGEarth 和你的业务工程保持同一套 MSVC 运行库设置。2.3 目录规划源码、构建、安装、三方库四分离我一般把源码、构建目录、安装目录和三方库分开避免 CMake 把生成文件写回源码树也避免安装时把include、lib、bin混在一起。下面这套目录只是为了说明层级盘符和父目录可以换但四类目录的边界不要混。目录用途说明D:\dev\osg365\srcOSG、OSGEarth 源码只放解压后的源码不在这里编译D:\dev\osg365\buildCMake 构建目录每个配置一个子目录出问题直接删D:\dev\osg365\install安装前缀OSG 和 OSGEarth 可以共用前缀D:\dev\osg365\3rdParty预编译三方库保持原始include、lib、bin结构# 建立固定层级避免路径里出现空格和中文 $root D:\dev\osg365 New-Item -ItemType Directory -Force $root\src, $root\build, $root\install, $root\3rdParty | Out-NullNew-Item -Force在目录已存在时不会报错适合反复初始化环境。$root后面会同时出现在 CMake 参数和运行时 PATH 里所以尽量短、纯英文、无空格。路径越长Windows 下递归查找插件和依赖时越容易碰到边界情况。环境变量可以先只在当前 PowerShell 会话里设不要一上来就写系统环境变量。CMake 配置阶段仍然要显式传ACTUAL_3RDPARTY_DIRPATH 只负责运行时找 DLL两者不是一回事。# 当前会话临时设置关掉终端就失效适合先验证 $env:OSG_3RDPARTY_DIR D:\dev\osg365\3rdParty $env:OSG_ROOT D:\dev\osg365\install $env:Path $env:OSG_ROOT\bin;$env:OSG_3RDPARTY_DIR\bin;$env:PathOSG_3RDPARTY_DIR和OSG_ROOT是我自己用来记路径的变量真正传给 CMake 的仍然是后面的-D参数。Path里先放安装目录的bin再放三方库的bin是因为 OSG 自己的 DLL 可能依赖三方库 DLL顺序反了不一定立刻出错但排查缺库时会更绕。3. 配置 OSG 3.6.5CMake 选项、3rdParty 路径与 VS2019 编译OSG 这一层的关键不是把所有选项都打开而是让 CMake 准确找到 3rdParty并且生成器和架构一次成型。我见过不少环境是 CMake 配到一半改路径、改架构结果缓存里还留着旧值后面怎么编都不对。构建目录独立之后这种问题处理起来很简单路径大改就删构建目录重来。3.1 CMake 入口ACTUAL_3RDPARTY_DIR 要指到根不是 libOSG 的 CMake 用ACTUAL_3RDPARTY_DIR指定三方库根目录。这里要指到包含include、lib、bin的那一层不是lib也不是某个具体库的目录。CMAKE_INSTALL_PREFIX指向安装前缀编译完成后执行INSTALL目标头文件、库和可执行文件会按 OSG 的布局落进去。cd D:\dev\osg365\src\OpenSceneGraph-3.6.5 cmake -S . -B D:\dev\osg365\build\osg-vs2019-x64 -G Visual Studio 16 2019 -A x64 -DACTUAL_3RDPARTY_DIRD:/dev/osg365/3rdParty -DCMAKE_INSTALL_PREFIXD:/dev/osg365/install -DBUILD_OSG_EXAMPLESOFF-S .表示当前目录是源码根目录-B指定构建目录二者分离后源码树不会被污染。-G Visual Studio 16 2019和-A x64必须成对出现只写生成器不写架构CMake 可能按默认架构生成。ACTUAL_3RDPARTY_DIR用正斜杠是为了减少 CMake 对反斜杠转义的误判在 PowerShell 里路径本身仍然可以正常解析。BUILD_OSG_EXAMPLESOFF是我一般会关掉的选项示例工程会拉长编译时间排错阶段没必要全编。等osgversion、osgviewer能跑通再回头打开示例也不迟。若你的项目依赖示例里的某些数据或工具再单独打开不要一上来全量编译。3.2 生成 VS2019 工程先 Release再 DebugOSG 是双配置生成器Release 和 Debug 会生成不同的库。先编 Release 验证主链路再编 Debug 验证调试库不要两个配置的 DLL 混拷到同一个目录。Release 通过后再处理 Debug能把“架构问题”和“配置混用问题”分开。# 先编 Release 并安装 cmake --build D:\dev\osg365\build\osg-vs2019-x64 --config Release --target INSTALL --parallel--config Release指定当前构建配置--target INSTALL触发安装规则--parallel让 VS 生成器并行编译。安装完成后D:\dev\osg365\install\bin下应该有 OSG 的可执行文件和 DLLinstall\lib下应该有导入库install\include下应该有头文件。不要只编译ALL_BUILD就以为装好了INSTALL才会把文件按前缀铺开。# Release 验证通过后再编 Debug cmake --build D:\dev\osg365\build\osg-vs2019-x64 --config Debug --target INSTALL --parallelDebug 安装时注意观察bin和lib里是否出现带d后缀的文件以及和三方库的 Debug 版本是否匹配。若三方库只提供 Release 库Debug 配置下链接失败并不奇怪这时要么补 Debug 三方库要么让调试工程也链接 Release 三方库并明确运行库设置不能靠改文件名硬骗链接器。3.3 安装到 prefixinclude、lib、bin 各管什么安装前缀确定后后面 OSGEarth 会把它当作OSG_DIR。所以这个前缀不是随便找个目录就行它要能稳定存在并且包含 OSG 的 CMake 配置文件。安装完成后可以先看目录不要急着编 OSGEarth。路径内容用途install\includeOSG 头文件编译业务工程时使用install\lib.lib导入库、CMake 配置链接和find_package使用install\bin.dll、osgversion.exe、osgviewer.exe运行时和验证使用install\bin\osgPlugins-3.6.5OSG 插件 DLL读写不同模型格式时使用如果 CMake 配置阶段报找不到 ZLIB、PNG、JPEG 之类的依赖先回到ACTUAL_3RDPARTY_DIR检查根目录是否指错再看3rdParty\lib下有没有对应架构的库。不要一上来手工填ZLIB_LIBRARY、PNG_LIBRARY这类变量手工填多了以后换机器很难复现。构建目录里缓存了旧路径时直接删掉build\osg-vs2019-x64重新生成比在 CMake GUI 里逐项清理更省心。4. 接上 OSGEarth依赖查找、链接顺序与插件目录OSGEarth 是建立在 OSG 之上的它既要找到 OSG 的库和头文件也要找到三方库里的依赖。OSG 装完之后OSGEarth 这一层最容易出问题的地方是OSG_DIR指错、插件目录没进运行时搜索路径以及 Debug/Release 的 OSG 库混用。把这三件事分开看排查会快很多。4.1 OSGEarth 的 CMake 配置项OSG_DIR 指安装前缀OSG_DIR我一般指到 OSG 的安装前缀不是源码目录也不是bin。CMake 会在这个前缀下找 OSG 的配置文件和库。CMAKE_PREFIX_PATH同时把 OSG 安装前缀和 3rdParty 根目录放进去让find_package有更多查找位置。两者都写不冲突反而在换包布局时更容易命中。cd D:\dev\osg365\src\osgearth-src cmake -S . -B D:\dev\osg365\build\osgearth-vs2019-x64 -G Visual Studio 16 2019 -A x64 -DOSG_DIRD:/dev/osg365/install -DCMAKE_PREFIX_PATHD:/dev/osg365/install;D:/dev/osg365/3rdParty -DCMAKE_INSTALL_PREFIXD:/dev/osg365/installOSG_DIR指到安装前缀后CMake 才能沿着lib下的配置去找 OpenSceneGraph。CMAKE_PREFIX_PATH里的分号是列表分隔符不是普通路径字符在 PowerShell 里整体用双引号包住避免分号被当成命令分隔。CMAKE_INSTALL_PREFIX和 OSG 共用一个前缀是为了后面bin、lib、include能集中在同一棵树下运行时 PATH 也好写。如果配置阶段仍然提示找不到 OSG不要马上怀疑 OSGEarth 源码。先在安装前缀下找OpenSceneGraphConfig.cmake的实际位置再用OpenSceneGraph_DIR指向它所在目录。这个变量和OSG_DIR不是同一个层级的东西一个偏前缀一个偏配置文件目录混用会让人绕很久。# 查找 OSG 的 CMake 配置文件确认安装前缀下到底有什么 Get-ChildItem D:\dev\osg365\install -Recurse -Filter OpenSceneGraphConfig.cmake | Select-Object -ExpandProperty FullName查到路径后把OpenSceneGraph_DIR指到配置文件所在目录即可。不要在没查之前凭记忆写路径不同打包方式、不同安装规则都可能让配置文件落在不同子目录。这个习惯能省掉很多“明明装了却找不到”的时间。4.2 编译 OSGEarth插件和可执行文件不是同一个目录OSGEarth 编译完成后同样执行INSTALL。Release 先走一遍确认osgearth_viewer能启动再考虑 Debug。OSGEarth 的插件和 OSG 的插件可能安装在不同目录运行时需要分别加进搜索路径。不要只把install\bin加进 PATH 就认为插件一定能加载。cmake --build D:\dev\osg365\build\osgearth-vs2019-x64 --config Release --target INSTALL --parallel--target INSTALL会把 OSGEarth 的可执行文件、库和插件按安装规则铺到前缀下。编译过程中如果出现链接错误先看错误里缺的是 OSG 的库还是三方库的库。缺 OSG 库通常是OSG_DIR或配置缓存问题缺三方库通常是CMAKE_PREFIX_PATH没带 3rdParty或者 3rdParty 的架构和当前生成器不一致。提示OSGEarth 的插件目录名和安装布局以实际安装结果为准。编译完成后先列一遍install\bin及其子目录把插件 DLL 所在目录记下来后面配OSG_LIBRARY_PATH时直接使用真实路径不要照搬别人的目录名。4.3 运行期PATH 和 OSG_LIBRARY_PATH 解决的不是同一个问题Windows 加载 DLL 靠 PATHOSG 查找插件靠OSG_LIBRARY_PATH。程序双击闪退、提示找不到osg.dll通常是 PATH 没包含install\bin和3rdParty\bin程序能启动但加载模型时报no plugin found通常是插件目录没进OSG_LIBRARY_PATH。这两个问题经常被混在一起结果改了半天 PATH 也没解决插件加载。# 运行时搜索路径先 OSG/OSGEarth再三方库 $env:Path D:\dev\osg365\install\bin;D:\dev\osg365\3rdParty\bin;$env:Path # 插件搜索路径按实际插件目录填写分号分隔 $env:OSG_LIBRARY_PATH D:\dev\osg365\install\bin\osgPlugins-3.6.5;D:\dev\osg365\install\binPath是给 Windows 加载器用的OSG_LIBRARY_PATH是给 OSG 插件注册表用的。把install\bin同时放进两个变量不浪费因为 OSG 自身 DLL 和部分插件可能就在同一层。若插件目录实际不叫osgPlugins-3.6.5以你安装出来的目录为准不要为了照抄命令去改目录名。Debug 和 Release 的 DLL 不要放在同一个目录里混用。调试时用 Debug 的 PATH发布时用 Release 的 PATH最省事的做法是分别开两个终端会话而不是在一个 PATH 里同时塞两套库。5. 常见问题排查VS2019 下 OSG/OSGEarth 装完跑不起来的 4 个坑这一层的问题大多不是“代码写错了”而是编译期和运行期的搜索路径、架构、配置没有对齐。下面几条是我在 VS2019 环境里踩坑比较多的记录按“现象 → 原因 → 解决”拆开看比只看一条报错更有用。5.1 CMake 找到了 3rdParty链接仍报 LNK2019现象CMake 配置阶段没有报缺 ZLIB、PNG但生成解决方案后链接 OSG 或 OSGEarth 时出现LNK2019 unresolved external symbol符号名往往指向三方库函数。原因CMake 找到了头文件不代表链接器找到了对应.lib也可能是找到了 32 位库而当前生成器是 x64。还有一种情况是 Debug 配置链接了 Release 三方库符号修饰对不上。解决先看链接错误里缺的符号属于哪个库再回到3rdParty\lib确认该库是否存在、架构是否匹配、Debug/Release 是否齐全。用dumpbin /headers检查.lib的机器类型用dumpbin /dependents检查最终 DLL 的依赖。不要用“把能找到的 lib 全塞进附加依赖项”这种方式硬顶链接顺序和运行库冲突会越滚越大。5.2 编译通过运行提示找不到 osg.dll 或 0xc000007b现象VS2019 里编译成功双击osgviewer.exe或自己的程序时提示找不到osg.dll或者直接报0xc000007b程序连入口都没进去。原因找不到 DLL 是 PATH 没有包含install\bin和3rdParty\bin0xc000007b常见于 32 位程序加载了 64 位 DLL或者反过来。也有可能是 Debug 程序加载了 Release DLL依赖链里某一层架构不一致。解决先在命令行里用完整路径启动程序确认当前会话的 PATH 是否正确再用dumpbin /dependents看 EXE 依赖哪些 DLL逐个确认它们的架构。不要只看osg.dll一个文件三方库 DLL 也要一起检查。Debug 和 Release 分开终端验证避免两套 DLL 互相覆盖。5.3 osgviewer 能开加载 .earth 提示 no plugin found现象osgviewer能打开简单模型但用osgearth_viewer加载.earth文件时提示找不到插件或者某些图层驱动加载失败。原因OSG 插件和 OSGEarth 插件没有进入OSG_LIBRARY_PATH或者插件 DLL 缺少依赖加载到一半失败。还有一种情况是插件是 Debug 版而当前运行的是 Release 程序。解决列出安装目录下所有插件 DLL确认OSG_LIBRARY_PATH包含真实插件目录再用dumpbin /dependents检查插件 DLL 的依赖是否都能在 PATH 里找到。加载.earth时先简化图层只留一个最基础的影像或模型层确认插件链路通了再逐层加回。不要一上来就加载包含多种驱动和远程数据的完整工程文件排错面太大。5.4 Debug 下崩溃、Release 正常或反过来现象同一份代码 Release 能跑Debug 启动就崩或者 Debug 正常Release 加载模型时异常退出。原因最常见的是 Debug/Release 库混用包括 OSG、OSGEarth、3rdParty 和业务工程四层里有一层配置不一致。其次是 MSVC 运行库选项不一致/MD和/MT混用会在链接期或运行期埋雷。解决把 Debug 和 Release 的安装目录、PATH、CMake 构建目录彻底分开不要共用同一个bin。业务工程的“运行库”设置和 OSG/3rdParty 保持一致如果三方库只提供一种配置就在工程里明确对应配置不要靠改文件名伪装。这个问题没有太多捷径配置表对齐一次后面会省很多时间。6. 装完怎么验证用 osgversion、osgviewer 和 osgearth_viewer 跑通验证不要只看“编译成功”。我一般按三层走先看版本再看 OSG 自带工具能不能启动最后看 OSGEarth 能不能加载一个真实的.earth文件。三层都过才算这套 OSG3.6.5 OSGEarth VS2019 环境真正跑通。# 第一层版本和可执行文件 osgversion osgviewer --help # 第二层OSGEarth 工具与插件加载 osgearth_viewer --help # 第三层用项目里已有的 .earth 文件做实际加载 osgearth_viewer D:\dev\test-data\sample.earthosgversion能输出版本信息说明bin和依赖 DLL 基本就位osgviewer --help能正常退出说明 OSG 主库没有缺依赖osgearth_viewer --help能起来说明 OSGEarth 的可执行文件和核心库已经接上。最后用真实.earth文件加载才能验证插件目录、三方库 DLL 和数据驱动是否完整。检查项命令通过标准OSG 版本osgversion能输出版本号不闪退OSG 工具链osgviewer --help命令正常返回不提示缺 DLLOSGEarth 工具链osgearth_viewer --help能启动并打印帮助插件与数据osgearth_viewer sample.earth场景能加载控制台无插件缺失报错如果osgearth_viewer --help都起不来先回到 PATH 和install\bin不要急着怀疑.earth文件。如果帮助能起来但加载.earth失败再查OSG_LIBRARY_PATH和插件依赖。从那以后我每次装完 OSG 环境都强制走一遍“版本 → 工具 → 真实数据”的验证顺序不给自己留“编译过了应该没问题”的侥幸。希望帮到你。本文还有配套的精品资源点击获取
