gdal111编译版部署指南：环境变量配置与避坑实践

简介：预编译的GDAL 1.11版本，针对需要直接调用地理空间处理能力的开发者与GIS分析者，省去从源码编译的繁琐流程，开箱即用。其功能覆盖栅格数据的读取、写入、转换、裁剪与重采样，同时借助OGR模块支持Shapefile、GeoJSON等矢量数据操作，适合遥感影像预处理、地图制图及空间分析等场景。整个压缩包共241个文件，约3.46MB，结构紧凑。其中lib目录提供核心动态链接库与导入库，include目录包含72个C/C++头文件，供二次开发调用；bin目录内含22个可执行工具，可直接完成格式转换；data目录存放28个CSV坐标系统及投影参数文件，并附带WKT、GFS等辅助数据；html目录收录89个离线API文档，便于查阅函数用法。此外还包含DLL、XSD、XML等文件，组件齐全。当前已有297人学习下载，对需要轻量化集成GDAL的工程项目，这包预编译文件能显著降低环境搭建成本，快速支撑从影像镶嵌、矢量合并到坐标转换的日常任务。

1. 为什么还在用 gdal111：一个“老版本”解决新项目依赖的实例

前阵子接手一个 2015 年就冻结的 GIS 插件，日志里反复出现 gdal111.dll 加载失败。GDAL gdal111 正是那套项目锁死的版本：新一代机器上想直接跑，没有这个 dll 一切白搭。GDAL 是栅格处理的基石库，OGR 管矢量，而 gdal111 指 1.11.x 这条版本线，也是 GDAL 2.0 大改版之前的最后稳定线。自己从源码编一遍要准备编译器、第三方依赖，还要排错，而 GISInternals 这类站点把编译好的 GDAL 直接挂出来，解压就能用。

这份编译版对三类人最有用：接手老项目要做维护的工程师、写 C/C++ 插件必须在 1.11 的 ABI 下编译的开发者、以及不想在编译上耗时间只想验证流程的入门者。我这次拆的，就是拿到这套编译版之后从配置到调用的完整路径，包括那些翻过车才知道的细节。

2. 先看懂 gdal111 编译版：版本脉络、文件组成与适用边界

2.1 gdal111 到底指什么：1.11.x 那条 GDAL 版本线

gdal111 不是一个虚构的代号，它对应的就是 GDAL 1.11 分支，版本线最后停在 1.11.5。这个版本在 GDAL 的历史里位置很特殊：它是 2.0 大改版之前的最后一个稳定线。2.0 里栅格模型、驱动体系、C++ API 都做了破坏性调整，很多在 2014 到 2016 年之间编译的项目，A依存关系全都锁死在 1.11 的接口上。

从工程角度理解，1.11 的 C API 已经是给后期 2.x、3.x 打样的底子，GDALAllRegister、GDALOpen、RasterIO 这些函数名一直延续下来。但 C++ API 不一样，类内部的成员布局在 2.0 里改过，如果你用一个 2.x 的头文件去编译代码，再运行时加载 1.11 的 dll，大概率是内存布局错位，直接崩溃在看似人畜无害的成员函数调用上。这就是为什么很多老项目宁可继续用 1.11，也不愿意做一次看起来不太难的大版本迁移。

还有一个很多人忽略的事实：1.11 的 OGR 已经和 GDAL 统一成一个库了，你不需要单独找什么 ogr dll。所以 gdal111.dll 这个文件里，栅格驱动、矢量驱动、坐标转换核心是合在一起的，出了问题排查范围会小一些。你要是见到某个资源压缩包只放了 bin 和 data 两个文件夹，没有 plugins，那多半是静态编译的裁剪版，能用但驱动不全。

2.2 编译版资源里都有什么：bin、lib、data、plugins 逐个说

GISInternals 这类站点给的编译版，解压之后基本是这样一个布局：

bin 里的 gdal111.dll 是核心，exe 都是依赖它来跑的。lib 目录给 C/C++ 开发用，gdal_i.lib 是导入库，链接期需要，运行期不参与。include 里我特别提醒：gdal.h 是 C 接口头文件，gdal_priv.h 是 C++ 内部头文件，写插件的人基本绕不开这两个。ogrsf_frmts.h 是 OGR 矢量功能的关键入口，老代码里常出现。

data 目录最容易被漏掉。里面那一堆 csv 和 wkt 文件是坐标系统描述表。GDAL 启动时需要读取它们，否则 EPSG:4326 这种编号完全无法解析，你调用投影转换会得到“unknown coordinate system”之类的报错。plugins 目录在 1.11 编译版里是把驱动拆成一个个 DLL，比如矢量格式的 ogr_geojson.dll、栅格格式的 gdal_gtiff.dll。这样设计的好处是主库体积小，坏处就是你少配一个环境变量，驱动就悄悄缺一堆。

2.3 什么场景该选编译版而不是自编译：三条判断标准

很多新手拿到编译版第一反应是怀疑：这东西可信吗？要不要自己编？我的判断标准很简单，满足任何一条就果断用编译版。

第一条，目标机器上只有运行环境没有编译器。自编译至少要装 VS 或者 mingw，再拉一堆依赖库，耗时长且容易中途放弃。编译版解压就能用，适合交付场景。

第二条，你的代码是在 1.11 的 API 下写的，需要精准的 ABI 兼容。自编译如果编译器版本、运行时库配置和原来的不一样，编出来的 ABI 可能也有差异。GISInternals 的编译版用固定工具链，反而是一个相对稳定的参照。

第三条，需要绿色免安装部署。编译版不需要注册表写入，不需要安装服务，拷贝目录就能迁移。

反过来说，什么情况要自编译？你要裁剪驱动，比如只留三五个格式；你要改 GDAL 源码或者加钩子；你要用的第三方库版本和编译版冲突。这几类情况编译版救不了你。

3. 把 gdal111 装进项目：环境变量、依赖检查和最小可运行验证

3.1 环境变量配置：PATH、GDAL_DATA、GDAL_DRIVER_PATH 三条命

拿到编译版第一件事不是写代码，而是把环境变量配好。我建议把解压目录定成一个固定路径，比如 D:\gdal111，然后在当前 shell 里先验证一遍：

export GDAL_HOME=/d/gdal111 export PATH=$GDAL_HOME/bin:$PATH export GDAL_DATA=$GDAL_HOME/data export GDAL_DRIVER_PATH=$GDAL_HOME/plugins

Windows 下这套命令的对应写法是 set PATH=D:\gdal111\bin;%PATH%，set GDAL_DATA=D:\gdal111\data，set GDAL_DRIVER_PATH=D:\gdal111\plugins。PATH 负责让系统找到 gdal111.dll 和 exe，GDAL_DATA 负责坐标系统表，GDAL_DRIVER_PATH 负责让 GDAL 去 plugins 目录扫驱动。三条缺一不可。

我个人习惯是把 GDAL_DATA 和 GDAL_DRIVER_PATH 直接做成系统环境变量，而不是只在当前 shell 里 set。因为很多时候程序不是从终端启动的，而是从桌面双击、从服务管理器拉起的，这些进程读不到 shell 里的临时变量。设置完之后记得把终端全部关掉重开，因为 Windows 的环境变量广播只对新的进程生效。

3.2 依赖排查：MSVC 运行库和第三方 DLL 的检查方法

解压完双击 gdalinfo.exe，最常见的翻车是弹窗提示“找不到 msvcp120.dll”或者“找不到 vcruntime140.dll”。这不是 GDAL 文件损坏，是机器上缺 Microsoft Visual C++ 运行库。GISInternals 编译的 GDAL 用的是 VS2013 或 VS2015 工具链，对应需要 vc_redist 运行库。

要确认某个 exe 或 dll 到底依赖什么，可以用 VS 自带的 dumpbin 命令：

dumpbin /dependents D:\gdal111\bin\gdal111.dll

输出里会列出 KERNEL32.dll、MSVCP120.dll、VCRUNTIME140.dll 这些依赖项。看到 MSVCP120 就去装 VS2013 的运行库，看到 VCRUNTIME140 就去装 VS2015-2022 那个合并版运行库。

注意一点，dumpbin 本身需要从 VS 的开发人员命令提示符里运行，普通 cmd 里找不到。不想开 VS 的话，可以用 Dependency Walker 这类绿色小工具拖进去看，效果一样。

还有一个容易翻车的点：PATH 里如果已经存在别的 GDAL，比如 QGIS 自带的某个版本，你会发现 gdalinfo 能跑，但版本号不对，或者一堆驱动显示不出来。所以检查依赖之前，先跑一下 where gdalinfo，确认它到底解析到哪个路径。我之前就有过一次这样的经历，排查了半天依赖，最后发现是 PATH 里的 QGIS 目录排在前面，整个调试方向都偏了。

3.3 最小化验证：用 gdalinfo 和 ogrinfo 确认编译版健康

环境变量配好、依赖没问题之后，做一次最小化验证，确认这个编译版是健康的：

gdalinfo --version gdalinfo D:\data\sample.tif ogrinfo --formats

第一行看版本号，确认是 GDAL 1.11.x，而不是 PATH 里混入了别的版本。第二行找一个真实的 tif 文件打开，看输出里是否包含 Driver: GTiff/GeoTIFF、Coordinate System、Size 这些关键字段。第三行列出所有矢量驱动，里面必须有 ESRI Shapefile、GeoJSON 这些常见项。

如果你发现 ogrinfo --formats 列出的格式列表和你解压的 plugins 目录对不上，比如某驱动在 plugins 里明明有 DLL，但列表里没有，那就要回到 GDAL_DRIVER_PATH 的检查上。我常遇到的情况是用户把路径写错了，多了一个斜杠或者空格，GDAL 扫不到就静默跳过。

4. 用 gdal111 干活：C/C++ 与 Python 两种调法的落地

4.1 C/C++ 调用：include、lib 配置和 GDALAllRegister 的坑

C/C++ 调用 gdal111 编译版，本质是让链接器找到 gdal_i.lib，让编译器找到头文件，然后运行期让系统找到 gdal111.dll。VS 工程里三处配置：C/C++ 附加包含目录填 include 路径，链接器附加库目录填 lib 路径，附加依赖项加 gdal_i.lib。

最小调用代码长这样：

#include "gdal_priv.h" #include "ogr_spatialref.h" int main() { GDALAllRegister(); // 1.11 版本无参数，注册全部驱动 GDALDataset* ds = (GDALDataset*)GDALOpen("D:\\data\\sample.tif", GA_ReadOnly); if (ds == NULL) { printf("open failed\n"); return -1; } int width = ds->GetRasterXSize(); int height = ds->GetRasterYSize(); printf("size: %dx%d\n", width, height); GDALClose(ds); return 0; }

这里有两个老版本的坑。第一个是 GDALAllRegister，在 1.11 里它是无参函数；到了 GDAL 2.x 有 GDALAllRegister 和 GDALAllRegisterEx 两个版本，参数也不一样。如果你拿 2.x 的示例代码硬套，编译大概率不过。第二个坑是 GDALOpen 返回的指针在 C++ 里要强转成 GDALDataset*，因为 C 接口返回的是 void*。有些新手忘了包含 gdal_priv.h，直接用 gdal.h 打开 C++ 数据集，编译能过但成员函数调不了。

调试的时候还有一个细节：如果代码里调用了 GDALOpen 但忘了先调 GDALAllRegister，返回值一定是 NULL，而且不会给你任何错误提示。因为 GDAL 还没有注册任何驱动，它根本不知道该怎么打开这个 tif。所以排查打开失败时，先确认注册调用有没有执行。

4.2 Python 绑定：从 GDAL 2.x 退到 1.11 的兼容性注意点

gdal111 时代的官方 Python 绑定，做得比较完善的是 Python 2.7 和 3.4。现在的主流 Python 3.8 以上要装 1.11 的绑定，pip 上很难找到对应 wheel，源码编译又容易因为 Cython 和头文件版本不一致出一堆问题。我的建议是别折腾，直接用 subprocess 调命令行工具：

import subprocess def gdal_version(): out = subprocess.run( ["gdalinfo", "--version"], capture_output=True, text=True ) print(out.stdout.strip()) def translate_wgs84_to_mercator(src, dst): subprocess.run([ "gdal_translate", "-a_srs", "EPSG:4326", "-of", "GTiff", src, dst ], check=True)

gdal_translate 参数里 -a_srs 是把源文件强制赋一个坐标系统，-of 指定输出格式，GTiff 是 GeoTIFF。这里我特意用 subprocess 而不是 os.system，因为 subprocess 能让你拿到返回码和标准输出，出问题时排查方便。check=True 会让命令失败时直接抛异常，避免流程继续跑出不可预料的结果。

如果你真的需要原生 Python 绑定，血泪经验是开一个干净的 conda 环境，锁 Python 3.4，然后用老版本的 setuptools 去编译。这个过程比较玄学，遇到编译错误要反复调 include 路径，我是建议非必要不碰。

4.3 命令行批量处理：用 gdal_translate 和 ogr2ogr 打通流程

日常做批量转换，编译版的命令行工具比写代码快得多。一个典型场景是把一批 WGS84 的 GeoTIFF 重投影到 Web 墨卡托：

for f in D:/data/src/*.tif; do name=$(basename "$f") gdal_translate -a_srs EPSG:4326 -t_srs EPSG:3857 -r bilinear \ -of GTiff "$f" "D:/data/out/$name" done

-a_srs 声明输入坐标系统，-t_srs 指定输出坐标系统，-r bilinear 是重采样方法，bilinear 对连续栅格效果好，如果做分类图应该用 near 保持整数值。这里我习惯在命令里显式加一下环境变量前缀，防止系统 PATH 被其他版本干扰：

GDAL_DATA=D:/gdal111/data GDAL_DRIVER_PATH=D:/gdal111/plugins gdal_translate ...

这个写法在 bash 里是临时给单条命令设置环境变量，不污染当前 shell。命令行工具是编译版里最值得反复使用的部分，很多你以为要写代码的活，实际一条命令就结束了。

5. 避坑：gdal111 编译版最常见的六个翻车现场

5.1 崩溃在 GDALAllRegister：插件 DLL 路径不匹配

现象：同一个程序在自己机器上跑得好好的，拷到另一台机器就崩溃在 GDALAllRegister 这一行，错误码也不稳定，有时候是 0xC0000005。

原因：目标机器的 GDAL_DRIVER_PATH 指向了另一个 GDAL 版本的 plugins 目录，或者指向了一个根本不存在的路径。GDAL 扫描到这个路径下 DLL 后尝试加载，加载到和主库版本不一致的插件就崩。

解决：在程序入口处显式用 CPLSetConfigOption("GDAL_DRIVER_PATH", "D:/gdal111/plugins") 设置路径，并且用绝对路径。不要依赖系统环境变量，因为环境变量在不同机器上不可控。

5.2 gdalinfo 能跑但 gdal_translate 报错：PATH 里混入了别的 GDAL

现象：gdalinfo --version 输出版本号是 1.11.5，但调用 gdal_translate 做投影转换时报出“invalid SRS”或者“找不到 proj.db”之类的错误。

原因：两个 exe 在 PATH 里被解析到了不同路径。gdalinfo 在你配的目录里找到了，gdal_translate 却被系统先匹配到了 QGIS 或者别的软件带的新版本。新版本 GDAL 2.x 用的是 proj.db 数据库，你给 1.11 设置的 GDAL_DATA 里有 gcs.csv 它不认识。

解决：跑 where gdalinfo 和 where gdal_translate 看两个路径，统一排在 PATH 最前面。我在本地习惯把编译版目录放到系统 PATH 的顶部，同时把 QGIS 的路径挪到后面。

5.3 中文路径和 UTF-8：GDAL 1.11 的编码坑

现象：文件路径全英文时一切正常，一旦目录里带上“数据”这样的中文名，GDALOpen 返回 NULL，命令行工具提示“No such file or directory”。

原因：Windows 控制台默认 ANSI 编码，中文路径在传递时被转换成本地代码页，GDAL 1.11 对路径解析走的是 C 运行时库，不认这种编码转换结果。

解决：命令行场景下先执行 chcp 65001 切到 UTF-8 代码页；代码场景里 C 接口传入路径前用 CP_UTF8 做一次转换；批量处理任务干脆把中间文件全部放在英文路径下，最后再改名。

5.4 网盘下载的文件被杀毒误删：DLL 签名和校验

现象：解压过程中没有任何报错，但运行时提示缺 ogr_geojson.dll，回头看目录，plugins 文件夹里确实少了文件。

原因：杀毒软件把编译版里没有数字签名的 DLL 当作风险文件隔离了，而且有些杀毒软件是静默处理，日志里才有记录。

解决：解压前先临时关闭实时防护，解压后把整个目录加进白名单。再校验一遍文件完整性，GISInternals 页面通常会附带 MD5 或者 SHA1，我每次下载后都会对一遍，防止传输损坏和误删。

5.5 和 Qt/其他库同时用：符号冲突与运行时库不一致

现象：程序里同时链接了 GDAL 和另一个用到 GEOS 的库，初始化正常，但某个几何运算结果莫名其妙错误，或者直接段错误。

原因：GDAL 编译版内部带有 GEOS 和 PROJ 的符号，这两个符号是全局可见的。程序里如果还链接了其他版本的 GEOS/PROJ，运行期符号解析就会发生覆盖，行为不可预测。

解决：把 GDAL 相关操作封装到一个独立模块，编译成单独的 dll，让宿主程序通过这个 dll 间接调用，避免全局符号交叉。我在实际项目里就是这么处理的，从根上隔离了符号冲突。

5.6 换到服务器跑不了：缺少 VC 运行库

现象：开发机上程序正常，部署到一台干净的 Windows Server 上，双击 exe 直接弹“缺少 VCRUNTIME140.dll”。

原因：开发机装了 VS，运行库齐全；服务器是纯净环境，没有装任何 VC 运行库。GDAL 编译版的 exe 和 dll 都依赖于这个运行库。

解决：在服务器上安装 vc_redist.x64.exe。不想装的话，把对应版本的 msvcp140.dll、vcruntime140.dll 复制到程序目录也可以，但这里要注意架构匹配，x64 程序必须放 64 位版本的 dll。

6. 让 gdal111 发挥余热：做一套免安装的 GIS 工具链

6.1 把编译版打包成绿色工具包

部署的最后一公里，是把编译版做成一个免安装的绿色工具包。我的做法是写一个 start.bat，用相对路径代替绝对路径，这样整个目录拷到哪里都能跑：

@echo off set BASE=%~dp0 set PATH=%BASE%bin;%PATH% set GDAL_DATA=%BASE%data set GDAL_DRIVER_PATH=%BASE%plugins cd /d %BASE% gdalinfo --version

这段脚本里的 %~dp0 会自动展开成 bat 文件所在的目录，所以目录改名、换机器、放到 D 盘或者 E 盘都不影响。启动器放在工具包根目录，所有依赖都从 bin、data、plugins 三个子目录里找，不触碰系统全局环境变量。

6.2 验证打包结果

打包完做一次闭环验证：解压到全新路径，运行 start.bat，确认版本号正确，再用 gdal_translate 跑一次重投影，最后用 ogrinfo 检查矢量驱动列表。这样一套绿色工具包可以直接交付给其它同事。

我第一次打包时就吃过亏，把环境变量写死在系统里，换台机器部署直接抓瞎。从那以后我每次打包都强制走一遍 start.bat 相对路径，再对压缩包做一次 SHA1 校验，确保发给别人的东西解压即用。希望帮到你。

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