GDAL/OGR编译实战：从源码配置到开箱即用的完整指南

简介面向GIS开发者的GDALOGR预编译开发包已编译、可直接使用省去自行编译源码的繁琐流程。包内含GDAL/OGR及其依赖的GEOS、PROJ库支持栅格与矢量数据的读写、格式转换、投影变换等操作适用于地图数据处理、遥感影像分析、地理编码与GIS服务开发等场景无论是Shapefile、GeoJSON等矢量数据还是TIFF、JPEG栅格影像均可直接读取与转换。压缩包共1751个文件大小约24.49MB以448个h头文件、405个cpp源文件、283个obj中间文件为主另含6个dll、6个lib链接库及26个exe命令行工具既便于C/C工程直接链接也可通过命令行完成格式转换和坐标投影。资源还附带构建配置、html文档、xml配置等辅助内容可帮助进阶用户按需调整或重新编译解压后即可进入开发借助这些开发者可在Visual Studio、CMake或Python环境中快速搭建空间数据处理工具。已有252人学习下载适合希望快速集成GIS能力、避免重复配置依赖库的开发者使用。 GDAL/OGR 在 GIS 和遥感圈子里基本属于绕不开的那类库。做空间数据处理、影像矫正、矢量格式转换随手就会用到它但真到了要自己编译一个开箱即用的版本时跟着一堆报错信息折腾一晚上也是常有的事。这篇文章就围绕GDAL/OGR 编译到手即用这条线把编译前的准备、编译参数选择、跨平台操作细节和典型坑位都过一遍。如果你是从没编译过 GDAL 的 C 开发者或者想在自己的服务端环境里静态编一个 GDAL 却总卡在依赖上又或者只是想要个带 Python 绑定的预编译版本这篇文章应该能帮到你。1. 编译 GDAL/OGR 前必须想清楚的几件事1.1 GDAL 和 OGR 到底是什么关系先简单说下背景。GDAL 的全称是 Geospatial Data Abstraction Library也就是地理空间数据抽象库。它最初主要处理栅格数据比如 GeoTIFF、HFA、NetCDF 这些影像格式OGR 则是后来并入的矢量数据引擎负责 Shapefile、GeoJSON、PostGIS、KML 等矢量格式的读写。虽然 OGR 现在已经被整合进 GDAL 的主工程老底子的文档和社区里还是习惯把两者合称GDAL/OGR。这个库的价值在于它给上层应用提供了一套统一的数据模型不管底层文件是二进制还是文本不管坐标参考系统是经纬度还是投影坐标你都能用同一套 API 去读取和转换。C、Python、Java、C# 都有对应的绑定命令行工具也齐全gdalinfo、ogr2ogr、gdal_translate 这些几乎成了行业标准操作。但正因为支持格式太多GDAL 的源码编译起来并不是一键完成的活儿。它的依赖树里既有 PROJ 这种坐标转换库也有 GEOS 这种几何运算库还有 tiff、png、jpeg 等传统图像库。不同的依赖搭配编出来的 GDAL能力差别会非常大这也是很多人决定自己编译的核心原因。1.2 为什么要自己编译而不是直接装现成的用现成预编译包其实很省心。Windows 上有 OSGeo4WLinux 可以用 apt 或 yum 直接装 gdal-bin、libgdal-devPython 环境里还能用 conda 安装 pyogrio 和 rasterio它们都自带 GDAL。但可以直接用和适合你的项目是两码事。预编译包一般会做最大兼容性处理很多高级功能未必开启。比如某些驱动格式需要额外授权或非开源依赖官方包为了省事会直接关掉又比如你想把 GDAL 静态链接进自己的 C 程序系统包默认通常是动态库还得额外折腾。最典型的是 NDVI 计算、传感器定标这些遥感场景经常需要用到 HDF4/5 驱动没在编译期打开的话运行期拿到文件只会报unsupported file format。自己编译的另一个好处是能控制优化级别。用-marchnative编译时编译器可以为当前 CPU 生成更快的指令影像处理这种计算密集场景实测能有不少提升。说白了如果你只是跑跑 ogr2ogr 转格式预编译包完全够用但如果你想在算法流水线里深度调用 GDAL或者要裁剪依赖体积、定制驱动列表自己编几乎是必经之路。1.3 依赖库选型全编、半编还是不编编译 GDAL 前最需要决策的就是依赖库范围。GDAL 的 driver 体系是插件式的每个驱动可以单独开启或关闭。在 CMake 配置阶段你会看到一大堆GDAL_ENABLE_DRIVER_*选项这其实是按需编译的核心机制。我的建议是分三类考虑基础必备类PROJ坐标转换、SQLite3、libtiff、libpng、libjpeg。这些是默认功能的地基无论如何都要装。格式相关类NetCDF、HDF4/5、OpenJPEGJPEG2000、PostgreSQL、MySQL、libkml。按实际项目需求勾选不要一股脑全开。可选优化类GEOS空间分析、libcurl网络瓦片、OpenCLGPU 加速。这些能显著扩大 GDAL 能力但也会增加编译时间和依赖复杂度。如果你只是想要一个能处理日常矢量数据的 GDAL其实只编 PROJ GEOS SQLite 就足够了编译时间大大缩短。等确定要处理特定格式再重新加驱动编译也不迟。GDAL 的编译系统设计得还算干净增量编译时加一两个驱动不会触发全量重编。2. 源码获取与编译系统选型2.1 源码从哪里拿最靠谱GDAL 官方源码托管在 GitHub 的 OSGeo/gdal 仓库发布版会在 gdal.org 下载页面同步放 tar.gz 压缩包。我个人更推荐直接从 GitHub Release 拉取稳定版比如 3.8.x、3.9.x 这类版本因为它们经过了完整回归测试配套文档和第三方绑定兼容性最好。不建议拿 GitHub 主干分支的 nightly 版来做生产编译虽然能体验最新 driver 和 API但 API 变动和依赖版本要求可能随时变化今天编过明天崩调试成本高。如果是做开源项目集成建议锁定一个大版本号比如只跟 3.9 系列这样后续维护方便。2.2 configure 老套路和 CMake 新套路GDAL 早期版本用的是 autoconf 体系操作方式就是经典的./configure make make install。但 GDAL 从 3.4 开始官方逐步把构建系统迁移到了 CMake并在 3.9 之后将 CMake 作为默认构建系统。现在新版本已经不支持 autoconf 了所以新项目直接学 CMake 才是正道。CMake 的好处是跨平台一致性好Windows、Linux、macOS 下可以用同一套配置思维。它默认是 out-of-source 构建也就是源码目录和构建目录分离不会弄脏源码树出问题直接删 build 目录重来非常方便。2.3 CMake 配置里最值得关注的参数CMake 配置阶段我一般重点关注这几个变量CMAKE_BUILD_TYPERelease 还是 Debug。生产环境用 Release调试 GDAL 底层问题时用 Debug。CMAKE_INSTALL_PREFIX安装路径。Linux 下我喜欢装到/usr/local/gdal方便卸载。GDAL_BUILD_OPTIONAL_DRIVERS是否构建所有可选驱动默认是 ON全编。GDAL_ENABLE_DRIVER_*具体驱动开关比如-DGDAL_ENABLE_DRIVER_GTiffON。GDAL_USE_*是否使用外部依赖库比如-DGDAL_USE_GEOSON、-DGDAL_USE_HDF5OFF。GDAL_BUILD_SHARED_LIBS动态库还是静态库。如果打算分发独立程序可以考虑关掉共享库改为静态链接。CMAKE_PREFIX_PATH依赖库的非标准安装路径。比如 PROJ 没装在系统默认路径时这里必须指定否则 cmake 会找不到头文件。3. Linux 下编译一个可直接用的 GDAL3.1 准备系统依赖我在 Ubuntu 上一般先装这么一组基础包sudo apt update sudo apt install -y build-essential cmake ninja-build \ libproj-dev proj-bin libgeos-dev libsqlite3-dev \ libtiff-dev libpng-dev libjpeg-dev \ libcurl4-openssl-dev libexpat1-dev \ libnetcdf-dev libhdf5-dev这里我推荐用ninja构建器编译并发度管理比 make 更好Ninja 在增量编译时速度优势也明显。如果你不需要 NetCDF 和 HDF5可以少装两个库同时记得在 CMake 配置时关闭对应选项。3.2 编译安装步骤和参数说明假设源码已经解压到~/gdal目录我习惯把构建目录放在源码外面cd ~/gdal cmake -S . -B build -G Ninja \ -DCMAKE_BUILD_TYPERelease \ -DCMAKE_INSTALL_PREFIX/usr/local/gdal \ -DCMAKE_PREFIX_PATH/usr/local/lib/cmake \ -DGDAL_USE_GEOSON \ -DGDAL_USE_HDF5OFF \ -DGDAL_BUILD_OPTIONAL_DRIVERSOFF \ -DGDAL_ENABLE_DRIVER_GTiffON \ -DGDAL_ENABLE_DRIVER_GMLON \ -DGDAL_ENABLE_DRIVER_GeoJSONON \ -DGDAL_ENABLE_DRIVER_ShapefileON这里解释一下关键选型逻辑。GDAL_BUILD_OPTIONAL_DRIVERSOFF是把分散的可选驱动先关掉再手工打开需要的这样能显著减少编译时间。我见过不少人在这一步图省事全开结果编译时间翻了几倍真正用到的驱动却寥寥无几。配置完之后开始编译安装cmake --build build sudo cmake --install build--install会把头文件、库文件、可执行文件装到/usr/local/gdal下。如果不想污染系统路径这个 prefix 是很好的选择。3.3 环境变量配置编译装好只算完成一半运行时还要让系统能找到库和命令。在~/.bashrc里追加export GDAL_HOME/usr/local/gdal export PATH$GDAL_HOME/bin:$PATH export LD_LIBRARY_PATH$GDAL_HOME/lib:$LD_LIBRARY_PATH export C_INCLUDE_PATH$GDAL_HOME/include:$C_INCLUDE_PATH export CPLUS_INCLUDE_PATH$GDAL_HOME/include:$CPLUS_INCLUDE_PATH然后source ~/.bashrc生效。LD_LIBRARY_PATH 这个变量最容易被忽略如果你编译时带着依赖程序运行时却提示找不到 libgdal.so十有八九就是这里没配好。4. Windows 下编译 GDAL 的操作要点4.1 依赖库的两种获取方式Windows 下自己编译 GDAL 的麻烦点主要在依赖。一种办法是用 vcpkggit clone https://github.com/Microsoft/vcpkg.git cd vcpkg .\bootstrap-vcpkg.bat .\vcpkg install gdal[core,geos,tiff,png,jpeg] --triplet x64-windowsvcpkg 会把 GDAL 连同依赖一并编好省去手动折腾。不过有些人不想引入整套 vcpkg 体系那就得手动准备依赖库头文件和 DLL这通常从 OSGeo4W 或 Conda 里提取然后将各个依赖放在同一个目录再用-DCMAKE_PREFIX_PATH指向该目录。4.2 使用 CMake Visual Studio 编译如果你选择手动编译源码用 Visual Studio 生成器是常见路径。假设已经装好 VS 2022cmake -S . -B build -G Visual Studio 17 2022 -A x64 -DCMAKE_BUILD_TYPERelease -DCMAKE_INSTALL_PREFIXC:/gdal -DGDAL_USE_GEOSON -DGDAL_BUILD_OPTIONAL_DRIVERSOFF -DGDAL_ENABLE_DRIVER_GTiffON cmake --build build --config Release cmake --install build注意-DCMAKE_BUILD_TYPE在 Visual Studio 生成器里不直接决定输出真正的 release 版本取决于--config Release。这条命令实际会生成 gdal300.dll或者对应版本号的 DLL和 gdalinfo.exe、ogrinfo.exe 等工具。4.3 DLL 放在哪里PATH 怎么配Windows 上编译完成后的直接用经常卡在 DLL 搜不到。Visual Studio 编译出来的 DLL 默认会有几十个依赖如果只是自己跑命令行工具把安装目录的bin文件夹加入系统 PATH 即可setx PATH C:\gdal\bin;%PATH%但如果要把 GDAL 嵌入到自己的 C 程序里记得把bin下的 DLL 复制到可执行文件同目录或者统一放到 Windows System32 目录下否则运行时会报 The code execution cannot proceed because gdal305.dll was not found。用 CMake 集成时更容易踩 DLL 坑因为头文件找到了、lib 导入库也链接了但运行时的 DLL 搜索路径不对。我建议在项目代码里用SetDllDirectory显式指定 GDAL bin 目录或者直接让构建脚本把 DLL 拷贝到目标目录。5. 编译过程中最常见的坑位和排查方法5.1 configure/cmake 阶段报找不到依赖配置阶段最常见的错误是Could NOT find PROJ (missing: PROJ_LIBRARY PROJ_INCLUDE_DIR)这说明 PROJ 没有安装或者安装了但 CMake 没找到。解决办法是给CMAKE_PREFIX_PATH指定 PROJ 的安装前缀。在 Linux 下如果系统装了 libproj-dev通常会出现在/usr或/usr/localCMake 能自动找到Windows 下手动安装时路径很关键。5.2 编译中途报类型冲突或未知标识符这类错误多半是依赖版本太新或太旧。比如 PROJ 从 6 到 9 的 API 发生了挺大变化GDAL 版本如果比 PROJ 老很多就会出现函数签名不匹配。处理办法是看编译报错的文件和函数名去 GDAL 文档里查对应版本对 PROJ 的最低要求。另一个常见的坑是多个版本库混用比如 PROJ 从 conda 来一份、系统又装了一份导致头文件和库文件版本对不上。排查时先用proj --version看版本再用find / -name libproj*看清楚到底被哪些路径污染。5.3 编译速度慢到怀疑人生GDAL 本身源码量非常大全量编译 20 到 40 分钟都很正常。想提速有几个经验用 Ninja 而不是 make并发调度更高效。关掉不需要的驱动这比任何编译优化都有效。如果 CPU 支持加上-j或者-j$(nproc)Ninja 默认会按核心数并行。在-DCMAKE_CXX_FLAGS里加-O2而不是-O3优化级别稍低但编译时间明显缩短。我实测过同一台机器上全驱动编译和按需编译的差距前者接近 40 分钟后者 8 分钟不到。所以编译慢的时候别急着换机器先检查你的驱动开关是不是开得太多。5.4 编译成功但运行报缺少动态库Linux 下常见报错error while loading shared libraries: libgdal.so.31: cannot open shared object file原因就是动态库路径没设置。解决办法是ldconfig /usr/local/gdal/lib或者在/etc/ld.so.conf.d/下新建一个 gdal.conf 并把目录写进去然后执行ldconfig。Windows 下对应的就是 DLL 搜索路径问题上面已经说过。5.5 版本不匹配导致 Python 绑定崩溃如果你需要 Python 绑定编译完 GDAL 之后还需要匹配 GDAL 版本的 pygdal或者直接用pip install pyogrio这种自带 GDAL 的轮子包。自己编译时最容易出现的问题是 C 库和 Python 绑定的 GDAL 版本不一致比如系统里同时存在通过 pip 安装的旧版二进制运行时一调用就段错误。我的经验是如果只是用 Python不要去手动编译 GDAL直接用 conda-forge 里的gdal它已经帮你处理好了依赖。只有在需要定制 C 接口或给别的语言写绑定的时候才值得自己编。6. 编译完成后怎么确认可以直接用6.1 基础命令验证安装完成后首先验证命令行工具gdalinfo --version ogrinfo --formats前者输出 GDAL 版本号比如GDAL 3.9.3, released 2024/01/01后者会列出所有可用矢量驱动。这里建议清理输出检查你关心的驱动是不是真的在列表里比如 Shapefile、GeoJSON、GML。gdalinfo /path/to/your/file.tif ogrinfo /path/to/your/file.shp能正常打印出元数据和图层结构说明基础功能没问题。6.2 C 程序里怎么调用CMake 集成时直接用find_package(GDAL REQUIRED)find_package(GDAL REQUIRED) target_include_directories(myapp PRIVATE ${GDAL_INCLUDE_DIRS}) target_link_libraries(myapp PRIVATE ${GDAL_LIBRARIES})如果使用自定义安装前缀需要在调 CMake 时加上cmake -S . -B build -DCMAKE_PREFIX_PATH/usr/local/gdal如果你编译的是静态库还可能要额外链接依赖库比如-lproj -lgeos -lsqlite3具体看生成的GDALConfig.cmake或gdal.pc来确认。6.3 Python 动态库绑定自己编译的 GDAL 默认不带 Python 绑定如果想用系统 Python 直接调用建议用 pip 安装对应的 pygdal-wheel 或者找官方 Python 绑定源码做构建pip install pygdal3.9.3.*但要注意版本号必须和你的 GDAL 完全一致3.9.3对应pygdal3.9.3.*否则会接口不匹配。这种方案适合对 GDAL 版本有严格要求的人。7. 一个更省事的取舍官方预编译包如果你对定制要求不高我其实更推荐先用官方预编译包。Windows 上 OSGeo4W 是一站式解决方案里面包含了 GDAL 以及配套的 PROJ、GEOS 和 Python 库双击安装就能从命令行调用 gdalinfo。Linux 上 apt 的gdal-bin和libgdal-dev对大多数场景也够了。但有一点要提醒发行版仓库里的 GDAL 版本通常滞后比如当前最新 3.9 系列Ubuntu 官方源可能还是 3.6。这使得用 gdal_translate 处理一些较新的传感器格式时会不支持。如果你有明确的新格式需求或者需要在自己的工具链里统一版本那还是自己编译一次更靠谱。我在团队项目里就是这么定的开发环境用官方预编译包发布环境用自己编译的静态链接版本这样既保证了开发效率又避免了部署机器上依赖库版本不一致的隐患。8. 最后分享一个我看家的编译技巧如果同一个 GDAL 源码你打算多次编译不同驱动组合建议第一次先全编一次之后每次只改动-DGDAL_ENABLE_DRIVER_*参数CMake 的增量编译能识别新增和移除的驱动并不会把整个库重编。我经常在一个构建目录里换来换去地调驱动比每次新建目录省太多时间。另外编译完记得保留好配置命令写进项目里的 README 或脚本。隔几个月之后回头重新编译时看着那十几条 CMake 参数我想不起来当时为什么这么设手写记录比猜要好太多。这套编译流程踩顺之后GDAL/OGR 基本就是等下就是一条命令的事。本文还有配套的精品资源点击获取