简介这份压缩包面向在 Windows 平台从事 GIS 开发、遥感数据处理与测绘软件构建的开发者提供 GDAL 3.0.0 在 Windows 10 与 Visual Studio 2019 下编译的静态库并集成 PROJ 与 SQLite3。它主要解决地理空间数据格式读取、坐标系投影转换、跨坐标系数据整合及本地元数据存储的依赖配置问题适合需要直接静态链接、避免运行时动态库版本冲突的 C 项目。包内共 340 个文件约 140.38MB包含大量 html 文档与 h 头文件便于查阅 API 和编译接入gfs、csv、xml、wkt 等文件对应坐标系定义与测试数据exe 工具可用于投影和格式转换验证另有 lib、db 等库与数据库文件。已有 642 人学习下载表明该构建组合在相关开发场景中具有一定参考价值。读者可据此获得一套较完整的静态链接开发环境快速开展栅格数据读取、坐标转换、VRT 元数据管理等任务减少自行编译与依赖匹配的时间并兼顾静态部署的便携性。1. 版本对不上GDAL 编译安装会白忙一晚GDAL 编译安装最常见的误解是以为只要 CMake 不报错就算装完了。实际有一次CMake 顺利通过make也编译成功一行代码没改但执行gdalinfo --version正常一读带投影信息的影像就报PROJ: proj_create_from_database: Cannot find proj.db。后来查了两小时发现 CMake 悄悄链接了系统自带的旧 PROJ而非我编译的那一份。GDAL、PROJ、SQLite3 三个库必须按正确顺序、统一安装目录、统一符号链接来安装顺序乱一步就会整晚白费。这篇记录适合要在离线或内网机器上编译 GDAL 3.x 的人也适合拿到一份 release 构建包却不知道如何接入工程的人。2. 定版本GDAL、PROJ、SQLite3 的咬合关系动手前先把版本关系理清这是整个编译过程中最省时间的一步。GDAL 3.x 的坐标转换全部由 PROJ 提供PROJ 6 以后又把坐标系统数据库从文本文件改为 SQLite 数据库proj.db因此 SQLite3 从可选的附加依赖变成了硬性依赖。三个库像齿轮一样相互依赖SQLite3 的版本决定 PROJ 能否正常生成数据库PROJ 的版本决定 GDAL 的坐标转换 API 能否对上而 GDAL 的版本又决定它要求 PROJ 提供哪些接口函数。2.1 为什么 GDAL 3.x 必须挂在 PROJ 6 以上GDAL 2.x 时代自带一套 EPSG 文本文件解析逻辑坐标转换靠内部的ogr_srs_apiPROJ 只是在投影运算时被调用。到了 GDAL 3.0这套逻辑被整体删除OGRSpatialReference直接变成 PROJ 的封装层ImportFromEPSG、SetFromUserInput全部转调proj_create。这意味着如果机器上存在 PROJ 5 或更早的版本GDAL 3.x 连编译都过不去头文件里proj.h的符号和静态检查会对不上。更隐蔽的问题是 PROJ 6 与 PROJ 9.x 之间的差异。PROJ 6 到 8 用PROJ_LIB环境变量指定数据目录PROJ 9.1 起正式引入PROJ_DATA同时把PROJ_LIB降级为兼容别名并在某些版本里打印弃用提醒。如果你的部署脚本里写死了PROJ_LIB升级 PROJ 之后日志里会多出警告而在某些打包构建下PROJ_LIB的优先级行为也有变化。我一般会直接把两个变量都设为同一个路径兼容新旧版本同时避免告警。版本选择上我倾向的组合是 GDAL 3.63.8、PROJ 9.29.3、SQLite 3.40 以上。这套组合发布稳定、资料多、下游生态Python 绑定、QGIS 类工具接受度最好。GDAL 3.9 之后进一步收紧了部分驱动的依赖检测如果你的业务里用了 ECW、MrSID 这类商业格式需要额外确认驱动是否可用别默认它们还在。2.2 版本对照与编译工具链清单下表是这套环境里我会对照检查的版本组合实际替换成手上的源码版本即可但三条版本约束不要破SQLite 版本要够 PROJ 生成数据库PROJ 要满足 GDAL 的最低版本Python 绑定的版本号必须与 libgdal 完全一致。组件建议版本作用关键约束GDAL3.6.x / 3.7.x / 3.8.x主库提供格式与坐标能力要求 PROJ 6.0实际按 9.x 用PROJ9.2.x / 9.3.x坐标转换与坐标系数据库需 SQLite3 生成proj.dbSQLite33.40 以上存放坐标系数据、GPKG 支持需同时提供库和命令行可执行文件CMake3.20 以上三个库统一构建系统GDAL 3.8 要求 3.16PROJ 9 要求 3.9C/C 编译器GCC 9 / VS2019编译源码需 C17 支持zlib、libtiff、libcurl系统包或内部编译GDAL 基础驱动的依赖未安装时可用 internal 模式工具链本身不难安装难在“一份 CMake 只找一个库”。Linux 下我会先执行apt list --installed | grep -E gdal|proj|sqlite把系统里已有的旧版本全部检查清楚Windows 下则要检查PATH里有没有别的proj.dll、sqlite3.dll抢先被加载。这一步看似琐碎但能挡住后面八成莫名其妙的链接错误。# 检查系统里已有的旧版本避免被 CMake 抢先找到 ldconfig -p | grep -E libproj|libgdal|libsqlite3 dpkg -l | grep -E proj|gdal|sqlite || rpm -qa | grep -E proj|gdal|sqlite which proj sqlite3 gdalinfoldconfig -p列出的是动态链接器缓存能看到每个库的实际路径和 SONAME。如果发现有多个libproj.so后面就必须显式指定PROJ_DIR不能指望 CMake 自己挑对的。which用来确认命令来自哪个安装前缀很多时候gdalinfo跑的是系统包里的版本你编译的那份根本没被调用到。2.3 解包这份 release 构建产物之前先看三件事拿到GDAL_BUILD(release).rar这类构建产物时不要急着把它当作可直接安装的发行版。它通常是某个环境里编译出来的头文件、库文件和命令行工具集合能否直接使用取决于目标机器的编译器版本、C 运行库版本和依赖库版本是否与构建环境一致。第一件事是解压路径。文件名里带圆括号在命令行里属于需要转义的字符Linux 下要写成GDAL_BUILD(release).rarWindows 下在 PowerShell 里要用引号包住。解压目标目录我一般固定在/opt/gdal-stack或D:\sdk\gdal路径里绝不出现中文和空格因为 CMake、pkg-config、部分 Python 绑定对空格路径的处理都出现过问题属于典型的“能省事就省事”的做法。第二件事是检查符号链接。在 Linux 上用 unrar 解 Windows 下打包的包libgdal.so这类软链接经常变成一个文本文件或 0 字节文件导致链接器读到的不是真正的库。执行ls -l lib/看libgdal.so是否指向libgdal.so.3x再看file libgdal.so.3x确认它是 ELF 共享库。如果软链接丢失就手动重建。第三件事是确认目标机器的 ABI 是否一致。用readelf -d libgdal.so.3x | grep NEEDED查看它依赖的 C 运行库版本如果依赖libstdc.so.6.0.29而目标机只有更低版本运行时就会报GLIBCXX_3.4.29 not found这种情况下改链接或升级运行库都可能很麻烦更稳妥的是回到源码自己编译一份。# 解压并检查共享库完整性 mkdir -p /opt/gdal-stack unrar x GDAL_BUILD(release).rar /opt/gdal-stack/ ls -l /opt/gdal-stack/lib/ | head -20 file /opt/gdal-stack/lib/libgdal.so* readelf -d /opt/gdal-stack/lib/libgdal.so.3x | grep -E NEEDED|SONAMEfile的输出会告诉你这是共享库还是被破坏的链接readelf -d的NEEDED段落列出它运行时需要的所有上层依赖SONAME决定程序运行时按哪个名字去找库。这一步做完心里就有数了是直接用这套库还是重编。3. 先把 SQLite3 和 PROJ 编出来两个硬依赖的顺序不能乱如果决定从源码编译顺序是 SQLite3 → PROJ → GDAL前一个的安装路径要成为后一个的查找路径。三者统一安装到同一个前缀比如/opt/gdal-stack能省掉大量环境变量工作也避免版本互串。这一章把前两步拆开写每一步都给出可复制的命令、参数含义和出问题时的观察点。3.1 SQLite3 源码编译--prefix 决定后面所有路径SQLite 的发行方式比较特别官方提供的是 amalgamation 合并源码或带 autoconf 的源码包。这里用sqlite-autoconf包它自带configure不需要额外安装 autotools。编译前先确认--prefix与后面 PROJ、GDAL 的前缀完全一致否则构建系统会找到系统默认路径下的 SQLite。# 编译安装 SQLite3 到统一前缀 cd /opt/src tar xzf sqlite-autoconf-3xxxxxx.tar.gz cd sqlite-autoconf-3xxxxxx ./configure \ --prefix/opt/gdal-stack \ --enable-shared \ --enable-static \ --disable-tcl \ CFLAGS-O2 -fPIC \ LDFLAGS-lm make -j$(nproc) make install # 确认库和命令行都在前缀下 ls -l /opt/gdal-stack/bin/sqlite3 /opt/gdal-stack/lib/libsqlite3.so*参数逐个说明--enable-shared是必须的PROJ 和 GDAL 默认按动态库链接--enable-static顺手编一份静态库某些离线环境里抢救用得上--disable-tcl关掉 Tcl 绑定避免因为机器上没有 tclsh 而编译中断CFLAGS-O2 -fPIC里的-fPIC不能省否则静态库被链接进共享库时会报relocation R_X86_64_32S can not be used。命令行工具sqlite3一定要装上很多人只装库不装 CLI结果 PROJ 编译过程中静默跳过了proj.db的生成步骤装完一堆文件却少了最关键的数据库文件。make install之后手动确认bin/sqlite3存在。3.2 PROJ 的 CMake 配置EXE_SQLITE3 和 proj.db 生成PROJ 的编译有两个关键点一是让 CMake 找到刚刚编译的 SQLite3二是让构建过程能调用sqlite3命令行把一批.sql文件导入并生成proj.db。前者靠CMAKE_PREFIX_PATH和显式的 include/lib 变量后者靠EXE_SQLITE3指向可执行文件的绝对路径。# 编译安装 PROJ指定 SQLite3 位置并生成 proj.db cd /opt/src tar xzf proj-9.x.x.tar.gz cmake -S proj-9.x.x -B build-proj \ -DCMAKE_BUILD_TYPERelease \ -DCMAKE_INSTALL_PREFIX/opt/gdal-stack \ -DCMAKE_PREFIX_PATH/opt/gdal-stack \ -DSQLITE3_INCLUDE_DIR/opt/gdal-stack/include \ -DSQLITE3_LIBRARY/opt/gdal-stack/lib/libsqlite3.so \ -DEXE_SQLITE3/opt/gdal-stack/bin/sqlite3 \ -DTIFF_ENABLEDON \ -DCURL_ENABLEDOFF \ -DBUILD_TESTINGOFF cmake --build build-proj -j$(nproc) cmake --install build-projSQLITE3_INCLUDE_DIR指向包含sqlite3.h的目录SQLITE3_LIBRARY指向具体的.so文件这两个值如果写错CMake 会回退到系统路径并在CMakeCache.txt里留下一条指向/usr/lib的记录后面排查时要特意去看缓存文件。EXE_SQLITE3是 PROJ 特有的选项如果它为空或指向一个不存在的文件构建不会失败但share/proj/proj.db不会生成安装后执行projinfo会直接报找不到数据库。TIFF_ENABLEDON用于支持 PROJ 的网格平移文件读取CURL_ENABLEDOFF在离线环境里建议关闭避免构建时因网络访问超时失败也避免程序运行时反复尝试远程拉取网格。BUILD_TESTINGOFF纯粹为了节省编译时间装完自己写验证脚本比跑它那套测试更直接。3.3 projinfo 自检确认 proj.db 能被读到PROJ 装完不要直接进入 GDAL 的编译先单独验证一遍。这一步花两分钟能省掉后面在 GDAL 里排查半小时的时间。export PATH/opt/gdal-stack/bin:$PATH export LD_LIBRARY_PATH/opt/gdal-stack/lib:$LD_LIBRARY_PATH export PROJ_DATA/opt/gdal-stack/share/proj export PROJ_LIB/opt/gdal-stack/share/proj # 确认版本、数据目录和数据库文件 projinfo --version ls -l /opt/gdal-stack/share/proj/proj.db projinfo EPSG:4326 -o PROJprojinfo --version输出里会列出编译时用的 SQLite 版本如果显示的数字比你编译的版本旧说明它链接到了系统库。proj.db应该有几 MB如果文件不存在或者只有几 KB就是生成步骤没有执行。projinfo EPSG:4326 -o PROJ是最有效的一行验证它要求 PROJ 真正打开数据库并做一次坐标系统查询成功时输出形如projlonglat datumWGS84 no_defs typecrs的字符串。如果这里报proj_create: no database context specified基本可以确定PROJ_DATA或旧版的PROJ_LIB指向的目录里没有proj.db。别急着去查 GDAL问题就出在这一层。4. 编译 GDAL 本体CMake 参数逐个拆开看前面两步做完GDAL 的编译反而成了最机械的一段但参数最多也最容易因为一个开关选错导致运行期缺能力。这一章按“先配置、再选开关、最后处理运行时路径”的顺序写。4.1 目录布局与第一次 CMake 配置源码目录和构建目录要分开构建目录不要放在源码目录里面否则清理起来很麻烦。我的习惯是/opt/src/gdal-3.x.x放源码/opt/src/build-gdal放构建产物安装前缀统一/opt/gdal-stack。# 首次配置 GDAL显式指定 PROJ 与 SQLite3 cd /opt/src tar xzf gdal-3.x.x.tar.gz cmake -S gdal-3.x.x -B build-gdal \ -DCMAKE_BUILD_TYPERelWithDebInfo \ -DCMAKE_INSTALL_PREFIX/opt/gdal-stack \ -DCMAKE_PREFIX_PATH/opt/gdal-stack \ -DPROJ_DIR/opt/gdal-stack/lib/cmake/proj \ -DSQLite3_INCLUDE_DIR/opt/gdal-stack/include \ -DSQLite3_LIBRARY/opt/gdal-stack/lib/libsqlite3.so \ -DGDAL_USE_SQLITE3ON \ -DBUILD_TESTINGOFFPROJ_DIR指向 PROJ 安装后生成的 CMake 配置目录GDAL 3.x 通过find_package(PROJ)加载它而不是用老式的FindPROJ.cmake。这个变量写对了版本就能对上写错或不写CMake 会去系统路径找找到旧版后仍然配置成功问题要等到运行时才暴露。CMAKE_PREFIX_PATH作为保底确保其他依赖也优先在前缀目录里查找。CMAKE_BUILD_TYPERelWithDebInfo是我在服务器环境里的默认选择保留调试符号便于事后用gdb或addr2line定位崩溃同时带-O2优化性能比纯 Debug 好很多。如果只是给内部工具用Release也行但出问题时就只能看到一串地址比较麻烦。配置完成后不要只看最后一行往上翻检查CMakeCache.txt里与 PROJ、SQLite3 相关的条目是否指向前缀路径。grep -E PROJ|SQLite /opt/src/build-gdal/CMakeCache.txt缓存文件里如果出现/usr/lib/x86_64-linux-gnu/libproj.so说明找错了直接删掉构建目录从头配置不要手工改缓存改完还会被其他依赖带偏。4.2 关键开关PROJ、SQLite3、驱动与 Python 绑定GDAL 的驱动数量很大全开会让编译时间拉长也会引入一堆不必要的外部依赖。我的原则是只开业务真正用到的格式其余用内置实现。# 第二次配置补充驱动选择与 Python 绑定 cmake -S gdal-3.x.x -B build-gdal \ -DGDAL_USE_SQLITE3ON \ -DGDAL_USE_TIFF_INTERNALON \ -DGDAL_USE_GEOTIFF_INTERNALON \ -DGDAL_USE_CURLOFF \ -DGDAL_USE_PNG_INTERNALON \ -DBUILD_PYTHON_BINDINGSON \ -DPython_EXECUTABLE/usr/bin/python3GDAL_USE_TIFF_INTERNALON让 GDAL 使用源码树里自带的 libtiff避免与系统 libtiff 的版本冲突。这个选项在有多个 GDAL 版本共存的机器上尤其重要外部 libtiff 的符号重复会导致加载时崩溃。GEOTIFF_INTERNAL同理用于 GeoTIFF 元数据支持。GDAL_USE_CURLOFF在离线环境里建议关闭如果业务需要读写远程对象存储或 HTTP 数据源需要打开并确认 libcurl 编译时启用了相应协议。这里需要说明的是关闭后/vsicurl/这类虚拟文件系统不可用如果现有脚本依赖它行为会发生变化所以要提前确认。BUILD_PYTHON_BINDINGSON会生成osgeo模块。这里有个必须强调的约束Python 绑定的版本号与libgdal的版本号必须严格一致否则导入时会抛RuntimeError: GDAL version mismatch。如果你打算用 pip 安装GDAL3.x.x那本地编译的libgdal也必须是对应的小版本不能只保证大版本相同。4.3 编译、安装与运行时库路径# 编译与安装 cmake --build build-gdal -j$(nproc) cmake --install build-gdal编译阶段内存占用不小-j的并行数按机器内存调整16G 内存的机器开到 8 比较稳开满核心数容易触发 OOM Killer。如果编译中途被系统杀掉日志里会看到c: fatal error: Killed signal terminated program cc1plus这时降低并行数重来即可不用怀疑代码。安装完成后处理运行时路径。有两种做法临时用环境变量或者写进系统配置。生产环境我倾向写一个独立的环境脚本方便回滚。# /etc/profile.d/gdal-stack.sh export GDAL_HOME/opt/gdal-stack export PATH$GDAL_HOME/bin:$PATH export LD_LIBRARY_PATH$GDAL_HOME/lib:$LD_LIBRARY_PATH export GDAL_DATA$GDAL_HOME/share/gdal export PROJ_DATA$GDAL_HOME/share/proj export PROJ_LIB$GDAL_HOME/share/projGDAL_DATA指向 GDAL 的辅助数据目录里面有坐标轴定义、单位换算表等文件缺了它某些格式的元数据解析会异常。PROJ_DATA和PROJ_LIB同时设置是为了兼容不同 PROJ 版本新版认前者老脚本认后者。如果不想依赖LD_LIBRARY_PATH可以在编译时就把 rpath 写进二进制这样可执行文件在别的 shell 里也能找到库cmake -S gdal-3.x.x -B build-gdal \ -DCMAKE_INSTALL_RPATH/opt/gdal-stack/lib \ -DCMAKE_BUILD_WITH_INSTALL_RPATHONCMAKE_INSTALL_RPATH会被写进 ELF 的RPATH段优先级高于系统默认搜索路径但低于LD_LIBRARY_PATH。CMAKE_BUILD_WITH_INSTALL_RPATHON让构建期就用安装路径省掉一次重新链接。用readelf -d bin/gdalinfo | grep -i path可以确认写进去了没有。5. 避坑编译期和运行期的五类翻车现场下面五条是这个组合里反复出现的故障。按“现象 → 原因 → 解决”的顺序记录方便对照日志直接修改。5.1 编译期三个高频报错第一条CMake 报Could NOT find PROJ (missing: PROJ_LIBRARIES PROJ_INCLUDE_DIR)。原因是机器上装了多个 PROJ或者安装的 PROJ 没有生成 CMake 配置文件find_package找不到可用目标。解决方法是先find /opt/gdal-stack -name proj-config.cmake -o -name PROJConfig.cmake确认文件位置然后用-DPROJ_DIR该目录显式指定如果确实没有配置文件改用PKG_CONFIG_PATH/opt/gdal-stack/lib/pkgconfig让 GDAL 走 pkg-config 分支。第二条链接阶段报undefined reference to proj_create_from_wkt之类的符号缺失。原因是编译时用的是新头文件、链接时找的是旧库头库版本不一致。解决方法是检查CMakeCache.txt里的PROJ_LIBRARY实际值并在LD_LIBRARY_PATH里把新库目录放到最前面必要时用-DCMAKE_EXE_LINKER_FLAGS-L/opt/gdal-stack/lib -Wl,-rpath,/opt/gdal-stack/lib强制链接顺序。第三条编译到一半被系统杀掉日志只有Killed。原因是并行编译时内存不足cc1plus被 OOM Killer 终止。解决方法是将-j降到 4 或 2 后重新执行cmake --build已经编过的目标不会重编不会浪费时间。5.2 运行期两个隐性故障第四条gdalinfo能跑但一读带坐标系的数据就报PROJ: proj_create_from_database: Cannot find proj.db。原因是PROJ_DATA没设置或指向了不存在的目录也可能是 PROJ 编译时没生成数据库。解决方法是先ls -l /opt/gdal-stack/share/proj/proj.db文件不存在就回第 3 章重新编译 PROJ确认EXE_SQLITE3有效文件存在就检查环境变量是否在执行的 shell 里生效env | grep PROJ注意sudo和 systemd 启动的服务不会继承登录 shell 的环境变量需要在服务单元里显式配置Environment。第五条Python 里from osgeo import gdal报RuntimeError: GDAL version mismatch或ImportError: libgdal.so.3x: cannot open shared object file。前者的原因是 pip 安装的osgeo版本与本地libgdal版本号不一致解决方法是卸载后按本地版本重装pip install GDAL对应版本需要先有libgdal的开发头文件后者的原因是动态链接器找不到库解决方法是在ld.so.conf.d/里加一行/opt/gdal-stack/lib后执行ldconfig比长期依赖LD_LIBRARY_PATH更可靠。6. 装完怎么验证三条命令确认这套环境真能跑装完不验证等于没装。我习惯用三层验证先确认版本和数据目录再确认格式与坐标能力最后确认动态库和 Python 绑定。三层都过这套环境才敢交给别人用。6.1 版本与数据目录自检第一层只看基础信息。gdalinfo --version输出的版本号必须和编译的版本一致gdalinfo --formats能看到 GTiff、GPKG 等关键格式gdalinfo --config不报错说明配置文件加载正常。gdalinfo --version gdalinfo --formats | grep -E GTiff|GPKG|SQLite echo $GDAL_DATA $PROJ_DATA ls $GDAL_DATA | head -5 ls $PROJ_DATA | grep proj.db如果--version输出的版本号对不上说明 PATH 里还有另一份gdalinfo用which -a gdalinfo全部列出来逐个排查。数据目录的检查不能省很多时候库装对了、数据文件没装全表现为某些格式能读能写但坐标系一塌糊涂。6.2 格式能力与坐标转换实测第二层做真实动作。用gdal_translate生成一个小文件再读回来用cs2cs做一次坐标转换这两步会把 PROJ 的数据库访问路径完整走一遍。# 生成一个 10x10 的测试栅格并读取元数据 gdal_create -of GTiff -outsize 10 10 -bands 1 -ot Byte /tmp/t.tif gdalinfo /tmp/t.tif | head -15 # 坐标转换经纬度到 Web 墨卡托 echo 116.4 39.9 | cs2cs EPSG:4326 EPSG:3857gdal_create是 GDAL 3.x 提供的命令行工具用来快速造测试数据比用 Python 写脚本快捷。cs2cs的输出应该是类似12956000 4852000的一组数能正常输出就说明 PROJ 的数据库和转换管线都通了如果报Cannot find proj.db回到第 3 章第 3 节的环境变量检查。6.3 动态库与 Python 绑定的最后一道检查第三层看运行时依赖和绑定版本。这两项出问题的概率最高也最容易被忽略。ldd /opt/gdal-stack/bin/gdalinfo | grep -E proj|sqlite|gdal readelf -d /opt/gdal-stack/lib/libgdal.so | grep RPATH python3 -c from osgeo import gdal, osr print(gdal, gdal.__version__) srs osr.SpatialReference() srs.ImportFromEPSG(4326) srs.SetAxisMappingStrategy(osr.OAMS_TRADITIONAL_GIS_ORDER) print(srs.GetAxisName(None, 0), srs.GetAxisName(None, 1)) ldd的输出里所有proj、sqlite3、gdal相关条目都应该指向/opt/gdal-stack/lib出现/usr/lib就是串了版本。readelf那行确认 rpath 写进去了输出为空说明没生效跨用户的脚本会找不到库。Python 那段的输出里版本号应与gdalinfo --version一致GetAxisName返回经度、纬度两个轴名说明坐标系统的轴序配置也正确。还有一个小技巧把这三层检查写成一个check-gdal.sh放进镜像构建流程里每次出新版本自动跑一遍比事后人工比对可靠。从那以后我每次换机器或者升级依赖都强制走一遍这套三层验证宁可多花三分钟也不想在业务代码里多调试两天。希望帮到你。本文还有配套的精品资源点击获取
简介这份压缩包面向在 Windows 平台从事 GIS 开发、遥感数据处理与测绘软件构建的开发者提供 GDAL 3.0.0 在 Windows 10 与 Visual Studio 2019 下编译的静态库并集成 PROJ 与 SQLite3。它主要解决地理空间数据格式读取、坐标系投影转换、跨坐标系数据整合及本地元数据存储的依赖配置问题适合需要直接静态链接、避免运行时动态库版本冲突的 C 项目。包内共 340 个文件约 140.38MB包含大量 html 文档与 h 头文件便于查阅 API 和编译接入gfs、csv、xml、wkt 等文件对应坐标系定义与测试数据exe 工具可用于投影和格式转换验证另有 lib、db 等库与数据库文件。已有 642 人学习下载表明该构建组合在相关开发场景中具有一定参考价值。读者可据此获得一套较完整的静态链接开发环境快速开展栅格数据读取、坐标转换、VRT 元数据管理等任务减少自行编译与依赖匹配的时间并兼顾静态部署的便携性。1. 版本对不上GDAL 编译安装会白忙一晚GDAL 编译安装最常见的误解是以为只要 CMake 不报错就算装完了。实际有一次CMake 顺利通过make也编译成功一行代码没改但执行gdalinfo --version正常一读带投影信息的影像就报PROJ: proj_create_from_database: Cannot find proj.db。后来查了两小时发现 CMake 悄悄链接了系统自带的旧 PROJ而非我编译的那一份。GDAL、PROJ、SQLite3 三个库必须按正确顺序、统一安装目录、统一符号链接来安装顺序乱一步就会整晚白费。这篇记录适合要在离线或内网机器上编译 GDAL 3.x 的人也适合拿到一份 release 构建包却不知道如何接入工程的人。2. 定版本GDAL、PROJ、SQLite3 的咬合关系动手前先把版本关系理清这是整个编译过程中最省时间的一步。GDAL 3.x 的坐标转换全部由 PROJ 提供PROJ 6 以后又把坐标系统数据库从文本文件改为 SQLite 数据库proj.db因此 SQLite3 从可选的附加依赖变成了硬性依赖。三个库像齿轮一样相互依赖SQLite3 的版本决定 PROJ 能否正常生成数据库PROJ 的版本决定 GDAL 的坐标转换 API 能否对上而 GDAL 的版本又决定它要求 PROJ 提供哪些接口函数。2.1 为什么 GDAL 3.x 必须挂在 PROJ 6 以上GDAL 2.x 时代自带一套 EPSG 文本文件解析逻辑坐标转换靠内部的ogr_srs_apiPROJ 只是在投影运算时被调用。到了 GDAL 3.0这套逻辑被整体删除OGRSpatialReference直接变成 PROJ 的封装层ImportFromEPSG、SetFromUserInput全部转调proj_create。这意味着如果机器上存在 PROJ 5 或更早的版本GDAL 3.x 连编译都过不去头文件里proj.h的符号和静态检查会对不上。更隐蔽的问题是 PROJ 6 与 PROJ 9.x 之间的差异。PROJ 6 到 8 用PROJ_LIB环境变量指定数据目录PROJ 9.1 起正式引入PROJ_DATA同时把PROJ_LIB降级为兼容别名并在某些版本里打印弃用提醒。如果你的部署脚本里写死了PROJ_LIB升级 PROJ 之后日志里会多出警告而在某些打包构建下PROJ_LIB的优先级行为也有变化。我一般会直接把两个变量都设为同一个路径兼容新旧版本同时避免告警。版本选择上我倾向的组合是 GDAL 3.63.8、PROJ 9.29.3、SQLite 3.40 以上。这套组合发布稳定、资料多、下游生态Python 绑定、QGIS 类工具接受度最好。GDAL 3.9 之后进一步收紧了部分驱动的依赖检测如果你的业务里用了 ECW、MrSID 这类商业格式需要额外确认驱动是否可用别默认它们还在。2.2 版本对照与编译工具链清单下表是这套环境里我会对照检查的版本组合实际替换成手上的源码版本即可但三条版本约束不要破SQLite 版本要够 PROJ 生成数据库PROJ 要满足 GDAL 的最低版本Python 绑定的版本号必须与 libgdal 完全一致。组件建议版本作用关键约束GDAL3.6.x / 3.7.x / 3.8.x主库提供格式与坐标能力要求 PROJ 6.0实际按 9.x 用PROJ9.2.x / 9.3.x坐标转换与坐标系数据库需 SQLite3 生成proj.dbSQLite33.40 以上存放坐标系数据、GPKG 支持需同时提供库和命令行可执行文件CMake3.20 以上三个库统一构建系统GDAL 3.8 要求 3.16PROJ 9 要求 3.9C/C 编译器GCC 9 / VS2019编译源码需 C17 支持zlib、libtiff、libcurl系统包或内部编译GDAL 基础驱动的依赖未安装时可用 internal 模式工具链本身不难安装难在“一份 CMake 只找一个库”。Linux 下我会先执行apt list --installed | grep -E gdal|proj|sqlite把系统里已有的旧版本全部检查清楚Windows 下则要检查PATH里有没有别的proj.dll、sqlite3.dll抢先被加载。这一步看似琐碎但能挡住后面八成莫名其妙的链接错误。# 检查系统里已有的旧版本避免被 CMake 抢先找到 ldconfig -p | grep -E libproj|libgdal|libsqlite3 dpkg -l | grep -E proj|gdal|sqlite || rpm -qa | grep -E proj|gdal|sqlite which proj sqlite3 gdalinfoldconfig -p列出的是动态链接器缓存能看到每个库的实际路径和 SONAME。如果发现有多个libproj.so后面就必须显式指定PROJ_DIR不能指望 CMake 自己挑对的。which用来确认命令来自哪个安装前缀很多时候gdalinfo跑的是系统包里的版本你编译的那份根本没被调用到。2.3 解包这份 release 构建产物之前先看三件事拿到GDAL_BUILD(release).rar这类构建产物时不要急着把它当作可直接安装的发行版。它通常是某个环境里编译出来的头文件、库文件和命令行工具集合能否直接使用取决于目标机器的编译器版本、C 运行库版本和依赖库版本是否与构建环境一致。第一件事是解压路径。文件名里带圆括号在命令行里属于需要转义的字符Linux 下要写成GDAL_BUILD(release).rarWindows 下在 PowerShell 里要用引号包住。解压目标目录我一般固定在/opt/gdal-stack或D:\sdk\gdal路径里绝不出现中文和空格因为 CMake、pkg-config、部分 Python 绑定对空格路径的处理都出现过问题属于典型的“能省事就省事”的做法。第二件事是检查符号链接。在 Linux 上用 unrar 解 Windows 下打包的包libgdal.so这类软链接经常变成一个文本文件或 0 字节文件导致链接器读到的不是真正的库。执行ls -l lib/看libgdal.so是否指向libgdal.so.3x再看file libgdal.so.3x确认它是 ELF 共享库。如果软链接丢失就手动重建。第三件事是确认目标机器的 ABI 是否一致。用readelf -d libgdal.so.3x | grep NEEDED查看它依赖的 C 运行库版本如果依赖libstdc.so.6.0.29而目标机只有更低版本运行时就会报GLIBCXX_3.4.29 not found这种情况下改链接或升级运行库都可能很麻烦更稳妥的是回到源码自己编译一份。# 解压并检查共享库完整性 mkdir -p /opt/gdal-stack unrar x GDAL_BUILD(release).rar /opt/gdal-stack/ ls -l /opt/gdal-stack/lib/ | head -20 file /opt/gdal-stack/lib/libgdal.so* readelf -d /opt/gdal-stack/lib/libgdal.so.3x | grep -E NEEDED|SONAMEfile的输出会告诉你这是共享库还是被破坏的链接readelf -d的NEEDED段落列出它运行时需要的所有上层依赖SONAME决定程序运行时按哪个名字去找库。这一步做完心里就有数了是直接用这套库还是重编。3. 先把 SQLite3 和 PROJ 编出来两个硬依赖的顺序不能乱如果决定从源码编译顺序是 SQLite3 → PROJ → GDAL前一个的安装路径要成为后一个的查找路径。三者统一安装到同一个前缀比如/opt/gdal-stack能省掉大量环境变量工作也避免版本互串。这一章把前两步拆开写每一步都给出可复制的命令、参数含义和出问题时的观察点。3.1 SQLite3 源码编译--prefix 决定后面所有路径SQLite 的发行方式比较特别官方提供的是 amalgamation 合并源码或带 autoconf 的源码包。这里用sqlite-autoconf包它自带configure不需要额外安装 autotools。编译前先确认--prefix与后面 PROJ、GDAL 的前缀完全一致否则构建系统会找到系统默认路径下的 SQLite。# 编译安装 SQLite3 到统一前缀 cd /opt/src tar xzf sqlite-autoconf-3xxxxxx.tar.gz cd sqlite-autoconf-3xxxxxx ./configure \ --prefix/opt/gdal-stack \ --enable-shared \ --enable-static \ --disable-tcl \ CFLAGS-O2 -fPIC \ LDFLAGS-lm make -j$(nproc) make install # 确认库和命令行都在前缀下 ls -l /opt/gdal-stack/bin/sqlite3 /opt/gdal-stack/lib/libsqlite3.so*参数逐个说明--enable-shared是必须的PROJ 和 GDAL 默认按动态库链接--enable-static顺手编一份静态库某些离线环境里抢救用得上--disable-tcl关掉 Tcl 绑定避免因为机器上没有 tclsh 而编译中断CFLAGS-O2 -fPIC里的-fPIC不能省否则静态库被链接进共享库时会报relocation R_X86_64_32S can not be used。命令行工具sqlite3一定要装上很多人只装库不装 CLI结果 PROJ 编译过程中静默跳过了proj.db的生成步骤装完一堆文件却少了最关键的数据库文件。make install之后手动确认bin/sqlite3存在。3.2 PROJ 的 CMake 配置EXE_SQLITE3 和 proj.db 生成PROJ 的编译有两个关键点一是让 CMake 找到刚刚编译的 SQLite3二是让构建过程能调用sqlite3命令行把一批.sql文件导入并生成proj.db。前者靠CMAKE_PREFIX_PATH和显式的 include/lib 变量后者靠EXE_SQLITE3指向可执行文件的绝对路径。# 编译安装 PROJ指定 SQLite3 位置并生成 proj.db cd /opt/src tar xzf proj-9.x.x.tar.gz cmake -S proj-9.x.x -B build-proj \ -DCMAKE_BUILD_TYPERelease \ -DCMAKE_INSTALL_PREFIX/opt/gdal-stack \ -DCMAKE_PREFIX_PATH/opt/gdal-stack \ -DSQLITE3_INCLUDE_DIR/opt/gdal-stack/include \ -DSQLITE3_LIBRARY/opt/gdal-stack/lib/libsqlite3.so \ -DEXE_SQLITE3/opt/gdal-stack/bin/sqlite3 \ -DTIFF_ENABLEDON \ -DCURL_ENABLEDOFF \ -DBUILD_TESTINGOFF cmake --build build-proj -j$(nproc) cmake --install build-projSQLITE3_INCLUDE_DIR指向包含sqlite3.h的目录SQLITE3_LIBRARY指向具体的.so文件这两个值如果写错CMake 会回退到系统路径并在CMakeCache.txt里留下一条指向/usr/lib的记录后面排查时要特意去看缓存文件。EXE_SQLITE3是 PROJ 特有的选项如果它为空或指向一个不存在的文件构建不会失败但share/proj/proj.db不会生成安装后执行projinfo会直接报找不到数据库。TIFF_ENABLEDON用于支持 PROJ 的网格平移文件读取CURL_ENABLEDOFF在离线环境里建议关闭避免构建时因网络访问超时失败也避免程序运行时反复尝试远程拉取网格。BUILD_TESTINGOFF纯粹为了节省编译时间装完自己写验证脚本比跑它那套测试更直接。3.3 projinfo 自检确认 proj.db 能被读到PROJ 装完不要直接进入 GDAL 的编译先单独验证一遍。这一步花两分钟能省掉后面在 GDAL 里排查半小时的时间。export PATH/opt/gdal-stack/bin:$PATH export LD_LIBRARY_PATH/opt/gdal-stack/lib:$LD_LIBRARY_PATH export PROJ_DATA/opt/gdal-stack/share/proj export PROJ_LIB/opt/gdal-stack/share/proj # 确认版本、数据目录和数据库文件 projinfo --version ls -l /opt/gdal-stack/share/proj/proj.db projinfo EPSG:4326 -o PROJprojinfo --version输出里会列出编译时用的 SQLite 版本如果显示的数字比你编译的版本旧说明它链接到了系统库。proj.db应该有几 MB如果文件不存在或者只有几 KB就是生成步骤没有执行。projinfo EPSG:4326 -o PROJ是最有效的一行验证它要求 PROJ 真正打开数据库并做一次坐标系统查询成功时输出形如projlonglat datumWGS84 no_defs typecrs的字符串。如果这里报proj_create: no database context specified基本可以确定PROJ_DATA或旧版的PROJ_LIB指向的目录里没有proj.db。别急着去查 GDAL问题就出在这一层。4. 编译 GDAL 本体CMake 参数逐个拆开看前面两步做完GDAL 的编译反而成了最机械的一段但参数最多也最容易因为一个开关选错导致运行期缺能力。这一章按“先配置、再选开关、最后处理运行时路径”的顺序写。4.1 目录布局与第一次 CMake 配置源码目录和构建目录要分开构建目录不要放在源码目录里面否则清理起来很麻烦。我的习惯是/opt/src/gdal-3.x.x放源码/opt/src/build-gdal放构建产物安装前缀统一/opt/gdal-stack。# 首次配置 GDAL显式指定 PROJ 与 SQLite3 cd /opt/src tar xzf gdal-3.x.x.tar.gz cmake -S gdal-3.x.x -B build-gdal \ -DCMAKE_BUILD_TYPERelWithDebInfo \ -DCMAKE_INSTALL_PREFIX/opt/gdal-stack \ -DCMAKE_PREFIX_PATH/opt/gdal-stack \ -DPROJ_DIR/opt/gdal-stack/lib/cmake/proj \ -DSQLite3_INCLUDE_DIR/opt/gdal-stack/include \ -DSQLite3_LIBRARY/opt/gdal-stack/lib/libsqlite3.so \ -DGDAL_USE_SQLITE3ON \ -DBUILD_TESTINGOFFPROJ_DIR指向 PROJ 安装后生成的 CMake 配置目录GDAL 3.x 通过find_package(PROJ)加载它而不是用老式的FindPROJ.cmake。这个变量写对了版本就能对上写错或不写CMake 会去系统路径找找到旧版后仍然配置成功问题要等到运行时才暴露。CMAKE_PREFIX_PATH作为保底确保其他依赖也优先在前缀目录里查找。CMAKE_BUILD_TYPERelWithDebInfo是我在服务器环境里的默认选择保留调试符号便于事后用gdb或addr2line定位崩溃同时带-O2优化性能比纯 Debug 好很多。如果只是给内部工具用Release也行但出问题时就只能看到一串地址比较麻烦。配置完成后不要只看最后一行往上翻检查CMakeCache.txt里与 PROJ、SQLite3 相关的条目是否指向前缀路径。grep -E PROJ|SQLite /opt/src/build-gdal/CMakeCache.txt缓存文件里如果出现/usr/lib/x86_64-linux-gnu/libproj.so说明找错了直接删掉构建目录从头配置不要手工改缓存改完还会被其他依赖带偏。4.2 关键开关PROJ、SQLite3、驱动与 Python 绑定GDAL 的驱动数量很大全开会让编译时间拉长也会引入一堆不必要的外部依赖。我的原则是只开业务真正用到的格式其余用内置实现。# 第二次配置补充驱动选择与 Python 绑定 cmake -S gdal-3.x.x -B build-gdal \ -DGDAL_USE_SQLITE3ON \ -DGDAL_USE_TIFF_INTERNALON \ -DGDAL_USE_GEOTIFF_INTERNALON \ -DGDAL_USE_CURLOFF \ -DGDAL_USE_PNG_INTERNALON \ -DBUILD_PYTHON_BINDINGSON \ -DPython_EXECUTABLE/usr/bin/python3GDAL_USE_TIFF_INTERNALON让 GDAL 使用源码树里自带的 libtiff避免与系统 libtiff 的版本冲突。这个选项在有多个 GDAL 版本共存的机器上尤其重要外部 libtiff 的符号重复会导致加载时崩溃。GEOTIFF_INTERNAL同理用于 GeoTIFF 元数据支持。GDAL_USE_CURLOFF在离线环境里建议关闭如果业务需要读写远程对象存储或 HTTP 数据源需要打开并确认 libcurl 编译时启用了相应协议。这里需要说明的是关闭后/vsicurl/这类虚拟文件系统不可用如果现有脚本依赖它行为会发生变化所以要提前确认。BUILD_PYTHON_BINDINGSON会生成osgeo模块。这里有个必须强调的约束Python 绑定的版本号与libgdal的版本号必须严格一致否则导入时会抛RuntimeError: GDAL version mismatch。如果你打算用 pip 安装GDAL3.x.x那本地编译的libgdal也必须是对应的小版本不能只保证大版本相同。4.3 编译、安装与运行时库路径# 编译与安装 cmake --build build-gdal -j$(nproc) cmake --install build-gdal编译阶段内存占用不小-j的并行数按机器内存调整16G 内存的机器开到 8 比较稳开满核心数容易触发 OOM Killer。如果编译中途被系统杀掉日志里会看到c: fatal error: Killed signal terminated program cc1plus这时降低并行数重来即可不用怀疑代码。安装完成后处理运行时路径。有两种做法临时用环境变量或者写进系统配置。生产环境我倾向写一个独立的环境脚本方便回滚。# /etc/profile.d/gdal-stack.sh export GDAL_HOME/opt/gdal-stack export PATH$GDAL_HOME/bin:$PATH export LD_LIBRARY_PATH$GDAL_HOME/lib:$LD_LIBRARY_PATH export GDAL_DATA$GDAL_HOME/share/gdal export PROJ_DATA$GDAL_HOME/share/proj export PROJ_LIB$GDAL_HOME/share/projGDAL_DATA指向 GDAL 的辅助数据目录里面有坐标轴定义、单位换算表等文件缺了它某些格式的元数据解析会异常。PROJ_DATA和PROJ_LIB同时设置是为了兼容不同 PROJ 版本新版认前者老脚本认后者。如果不想依赖LD_LIBRARY_PATH可以在编译时就把 rpath 写进二进制这样可执行文件在别的 shell 里也能找到库cmake -S gdal-3.x.x -B build-gdal \ -DCMAKE_INSTALL_RPATH/opt/gdal-stack/lib \ -DCMAKE_BUILD_WITH_INSTALL_RPATHONCMAKE_INSTALL_RPATH会被写进 ELF 的RPATH段优先级高于系统默认搜索路径但低于LD_LIBRARY_PATH。CMAKE_BUILD_WITH_INSTALL_RPATHON让构建期就用安装路径省掉一次重新链接。用readelf -d bin/gdalinfo | grep -i path可以确认写进去了没有。5. 避坑编译期和运行期的五类翻车现场下面五条是这个组合里反复出现的故障。按“现象 → 原因 → 解决”的顺序记录方便对照日志直接修改。5.1 编译期三个高频报错第一条CMake 报Could NOT find PROJ (missing: PROJ_LIBRARIES PROJ_INCLUDE_DIR)。原因是机器上装了多个 PROJ或者安装的 PROJ 没有生成 CMake 配置文件find_package找不到可用目标。解决方法是先find /opt/gdal-stack -name proj-config.cmake -o -name PROJConfig.cmake确认文件位置然后用-DPROJ_DIR该目录显式指定如果确实没有配置文件改用PKG_CONFIG_PATH/opt/gdal-stack/lib/pkgconfig让 GDAL 走 pkg-config 分支。第二条链接阶段报undefined reference to proj_create_from_wkt之类的符号缺失。原因是编译时用的是新头文件、链接时找的是旧库头库版本不一致。解决方法是检查CMakeCache.txt里的PROJ_LIBRARY实际值并在LD_LIBRARY_PATH里把新库目录放到最前面必要时用-DCMAKE_EXE_LINKER_FLAGS-L/opt/gdal-stack/lib -Wl,-rpath,/opt/gdal-stack/lib强制链接顺序。第三条编译到一半被系统杀掉日志只有Killed。原因是并行编译时内存不足cc1plus被 OOM Killer 终止。解决方法是将-j降到 4 或 2 后重新执行cmake --build已经编过的目标不会重编不会浪费时间。5.2 运行期两个隐性故障第四条gdalinfo能跑但一读带坐标系的数据就报PROJ: proj_create_from_database: Cannot find proj.db。原因是PROJ_DATA没设置或指向了不存在的目录也可能是 PROJ 编译时没生成数据库。解决方法是先ls -l /opt/gdal-stack/share/proj/proj.db文件不存在就回第 3 章重新编译 PROJ确认EXE_SQLITE3有效文件存在就检查环境变量是否在执行的 shell 里生效env | grep PROJ注意sudo和 systemd 启动的服务不会继承登录 shell 的环境变量需要在服务单元里显式配置Environment。第五条Python 里from osgeo import gdal报RuntimeError: GDAL version mismatch或ImportError: libgdal.so.3x: cannot open shared object file。前者的原因是 pip 安装的osgeo版本与本地libgdal版本号不一致解决方法是卸载后按本地版本重装pip install GDAL对应版本需要先有libgdal的开发头文件后者的原因是动态链接器找不到库解决方法是在ld.so.conf.d/里加一行/opt/gdal-stack/lib后执行ldconfig比长期依赖LD_LIBRARY_PATH更可靠。6. 装完怎么验证三条命令确认这套环境真能跑装完不验证等于没装。我习惯用三层验证先确认版本和数据目录再确认格式与坐标能力最后确认动态库和 Python 绑定。三层都过这套环境才敢交给别人用。6.1 版本与数据目录自检第一层只看基础信息。gdalinfo --version输出的版本号必须和编译的版本一致gdalinfo --formats能看到 GTiff、GPKG 等关键格式gdalinfo --config不报错说明配置文件加载正常。gdalinfo --version gdalinfo --formats | grep -E GTiff|GPKG|SQLite echo $GDAL_DATA $PROJ_DATA ls $GDAL_DATA | head -5 ls $PROJ_DATA | grep proj.db如果--version输出的版本号对不上说明 PATH 里还有另一份gdalinfo用which -a gdalinfo全部列出来逐个排查。数据目录的检查不能省很多时候库装对了、数据文件没装全表现为某些格式能读能写但坐标系一塌糊涂。6.2 格式能力与坐标转换实测第二层做真实动作。用gdal_translate生成一个小文件再读回来用cs2cs做一次坐标转换这两步会把 PROJ 的数据库访问路径完整走一遍。# 生成一个 10x10 的测试栅格并读取元数据 gdal_create -of GTiff -outsize 10 10 -bands 1 -ot Byte /tmp/t.tif gdalinfo /tmp/t.tif | head -15 # 坐标转换经纬度到 Web 墨卡托 echo 116.4 39.9 | cs2cs EPSG:4326 EPSG:3857gdal_create是 GDAL 3.x 提供的命令行工具用来快速造测试数据比用 Python 写脚本快捷。cs2cs的输出应该是类似12956000 4852000的一组数能正常输出就说明 PROJ 的数据库和转换管线都通了如果报Cannot find proj.db回到第 3 章第 3 节的环境变量检查。6.3 动态库与 Python 绑定的最后一道检查第三层看运行时依赖和绑定版本。这两项出问题的概率最高也最容易被忽略。ldd /opt/gdal-stack/bin/gdalinfo | grep -E proj|sqlite|gdal readelf -d /opt/gdal-stack/lib/libgdal.so | grep RPATH python3 -c from osgeo import gdal, osr print(gdal, gdal.__version__) srs osr.SpatialReference() srs.ImportFromEPSG(4326) srs.SetAxisMappingStrategy(osr.OAMS_TRADITIONAL_GIS_ORDER) print(srs.GetAxisName(None, 0), srs.GetAxisName(None, 1)) ldd的输出里所有proj、sqlite3、gdal相关条目都应该指向/opt/gdal-stack/lib出现/usr/lib就是串了版本。readelf那行确认 rpath 写进去了输出为空说明没生效跨用户的脚本会找不到库。Python 那段的输出里版本号应与gdalinfo --version一致GetAxisName返回经度、纬度两个轴名说明坐标系统的轴序配置也正确。还有一个小技巧把这三层检查写成一个check-gdal.sh放进镜像构建流程里每次出新版本自动跑一遍比事后人工比对可靠。从那以后我每次换机器或者升级依赖都强制走一遍这套三层验证宁可多花三分钟也不想在业务代码里多调试两天。希望帮到你。本文还有配套的精品资源点击获取
