GDAL 的 `--if / --input-format` 选项：精确指定输入驱动、绕过自动探测的完整指南

• GIS
• 遥感
• 数据工程

本篇技术指南围绕 GDAL 命令行统一工具家族共用的--if / --input-format <format>选项展开，讲解它如何指定打开输入数据集时尝试使用的格式驱动、如何重复声明多个候选驱动，以及在自动驱动探测失败或选错驱动时的实战价值。读完本文，你将掌握该选项的完整语法、可用范围、底层调用链（从参数解析到GDALOpenEx的驱动过滤），并能在gdal新式命令与gdalinfo、gdal_translate等传统工具中熟练运用它，处理无扩展名、多驱动竞争、格式识别歧义等棘手场景。

一、选项概览：语法、别名与核心语义

--if选项的官方定义位于 doc/source/programs/gdal_options/if.rst，核心语义可以概括为四点：

有两个容易混淆的边界需要特别强调，文档原文也明确指出了：

1. 它只是"尝试列表"，不是"强制列表"：--if并不会强制列出的驱动一定成功打开数据集。即便你指定了--if GTiff，如果文件内容并非 GTiff 能识别的内容，打开仍然会失败；
2. 驱动可能对文件扩展名有要求：某些驱动在识别时依赖文件扩展名（如部分矢量驱动），即使它们被列入--if候选，也可能因扩展名不匹配而拒绝打开。

二、为什么需要--if：自动驱动探测的局限

GDAL 打开任何数据集时，默认会遍历所有已注册驱动，依次调用其识别（Identify）与打开（Open）逻辑，直到某个驱动成功。这个流程的入口是GDALOpenEx（gcore/gdaldataset.cpp），最终由GDALDataset::Open（gcore/gdaldataset.cpp）执行"第一遍探测 + 可选第二遍延迟加载插件"的两轮扫描。

自动探测在以下场景容易出问题，这正是--if存在的意义：

• 文件无扩展名或扩展名不标准：自动探测完全依赖文件头（GDALOpenInfo预读的头部字节），某些格式头部特征不明显时可能识别失败；
• 多个驱动都能识别同一内容：探测顺序由驱动注册顺序决定，可能选到不是你想要的驱动；
• 相似容器格式竞争：例如同为栅格/同为 Zip 容器内嵌多种子格式时，自动选择可能与预期不符；
• 希望跳过探测开销：明确指定驱动可以避免逐驱动探测带来的无谓文件访问。

从源码结构看，GDALOpenInfo会保存允许驱动列表供各驱动识别时参考（papszAllowedDrivers成员，见 gcore/gdal_openinfo.h），并且自 GDAL 3.10 起提供了IsSingleAllowedDriver()方法（gcore/gdalopeninfo.cpp），用于判断某个驱动名是否为列表中唯一允许的驱动——可以推断，仅指定单个驱动时，驱动内部可以利用这一判断走更轻量的识别路径。

三、基本用法与实战示例

3.1 查看驱动短名

--if需要填入驱动短名。可以通过gdalinfo --formats或gdal --formats查看当前构建中所有已注册驱动及其短名，例如输出中的GTiff（GeoTIFF）、GPKG（GeoPackage）、netCDF等。短名必须与注册名完全一致（不区分大小写）。

3.2 指定单个输入驱动

传统工具与新版gdal命令均支持：

# 传统工具 gdalinfo --if GTiff data.tif gdal_translate --if GTiff data.tif out.tif # 新版 gdal 命令 gdal raster info --if GTiff data.tif gdal raster convert --if GTiff data.tif out.tif

注意：在gdal新式子命令语法中，--if属于全局输入选项，应放在子命令之后、输入文件名之前。

3.3 指定多个候选驱动

当不确定输入文件具体属于哪一种格式、但可以缩小到几个候选时，重复使用--if：

gdalinfo --if GTiff --if netCDF mystery.dat

GDAL 会按照命令行给出的顺序（结合驱动注册顺序）依次尝试这些驱动，直到成功。

3.4 与打开选项--oo搭配

--if经常与--oo（--open-option，详见 doc/source/programs/gdal_options/oo.rst）配合使用：先用--if锁定驱动，再通过--oo NAME=VALUE传入该驱动特有的打开选项，避免选项被其他驱动忽略或产生歧义。例如：

gdal raster info --if GTiff --oo OVERVIEW_LEVEL=2 data.tif

OVERVIEW_LEVEL是所有驱动通用的打开选项之一，用于选择特定的概览层级。

四、深层原理：从命令行参数到驱动过滤的完整调用链

4.1 参数解析：add_input_format_argument

新版gdal系列工具通过统一的GDALArgumentParser解析参数。--if的定义集中在 apps/gdalargumentparser.cpp 的add_input_format_argument()：

• 注册参数名-if，.append()表示可重复；
• 参数值存入CPLStringList（工具侧通常是aosAllowedInputDrivers）；
• 关键行为：每个值都会先调用GDALGetDriverByName()检查是否为已注册驱动，若不可识别，则发出CPLE_Warning级别的警告"%s is not a recognized driver"，但仍会将该字符串加入候选列表（后续打开时它自然匹配不到任何驱动）。

部分传统工具自带独立实现，例如 apps/gdal_translate_lib.cpp 中同样注册了--if，帮助文本为 "Format/driver name(s) to try when opening the input file."，行为与统一解析器一致：先校验驱动名、再追加到aosAllowedInputDrivers。

4.2 传递：GDALOpenEx的papszAllowedDrivers

以gdalinfo为例，解析得到的aosAllowedInputDrivers在 apps/gdalinfo_bin.cpp 中作为GDALOpenEx的第二个参数（papszAllowedDrivers）传入：

GDALDatasetH hDataset = GDALOpenEx( sOptionsForBinary.osFilename.c_str(), GDAL_OF_READONLY | GDAL_OF_RASTER | GDAL_OF_VERBOSE_ERROR, sOptionsForBinary.aosAllowedInputDrivers, sOptionsForBinary.aosOpenOptions, nullptr);

GDALOpenEx（gcore/gdaldataset.cpp）会将该列表直接灌入GDALOpenInfo并交给GDALDataset::Open。文档层面，if.rst被约 70 个程序页面通过.. include::复用，包括 gdal_raster_info.rst、gdal_mdim_info、gdal_vector_convert等，因此整个gdal命令家族的栅格、矢量、多维（MDIM）与外部命令都继承了该选项。

4.3 过滤：GDALDataset::Open中的驱动筛选

GDALDataset::Open（gcore/gdaldataset.cpp）在遍历驱动时执行如下过滤逻辑：

1. 若驱动短名匹配列表中的任一项，视为正向匹配；
2. 自 GDAL 3.13 起，列表项可以以-开头表示排除该驱动（该语义在GDALDataset::Open的参数注释中明确记载，见 gcore/gdaldataset.cpp）；
3. 若列表全部为排除项（bOnlyExcludedDrivers == true），则所有未被排除的驱动都视为候选；
4. 当驱动"未被正向匹配且列表并非全排除项"或"被负向匹配"时，直接continue跳过该驱动；
5. 通过过滤的驱动再按GDAL_OF_RASTER/GDAL_OF_VECTOR/GDAL_OF_MULTIDIM_RASTER等打开标志做能力过滤，随后进入Identify→Open两阶段探测。

由此可以推断：--if本质是在"驱动注册表全量探测"之前加了一道基于短名的预筛选，缩小探测范围而不改变探测机制本身——这也是文档强调"不强制打开"的原因：筛选之后，真正的识别与打开仍然由各驱动决定。

4.4 测试佐证

自动化测试中也能看到该选项的踪迹：autotest/utilities/test_gdal.py的补全测试用例（autotest/utilities/test_gdal.py）使用了gdal completion gdal raster info --if GTiff --open-option，验证了--if与--oo组合时 shell 补全仍能给出正确的打开选项建议，间接印证了--if与驱动级打开选项的关联。

五、注意事项与边界

• 不强制成功：--if只是候选名单；识别失败时打开依然失败，GDAL 不会因为"你指定了它"而放宽驱动自身的识别条件；
• 扩展名依赖：部分驱动（尤其矢量驱动）在Identify阶段依赖文件扩展名。例如对无扩展名的文件指定--if "ESRI Shapefile"，驱动仍可能因缺少.shp扩展名而拒绝；
• 驱动名校验仅警告：传入未注册的驱动名时只会产生 Warning，不会报错中断，最终因候选为空或无效而导致打开失败时，错误信息可能不如预期直观；
• 排除语法（GDAL 3.13+）：GDALOpenEx的papszAllowedDrivers支持-DriverName形式排除驱动；命令行侧同样可借助该语法，例如--if -PNG表示"除 PNG 外均可尝试"。需注意当前仓库版本为 3.14.0（见 VERSION），支持该语法；
• 与输出格式选项的区别：--if管输入、--of/--output-format管输出，二者不要混淆。

六、推荐实践小结

1. 平时不需要写--if，让 GDAL 自动探测；
2. 当打开失败、且确定文件内容是某已知格式时，用--if <DriverName>跳过探测歧义；
3. 多候选时重复--if，按可能性从高到低排列；
4. 需要排除干扰驱动时，使用--if -DriverName（3.13+）；
5. 配合--oo传入驱动专属打开选项，并用gdalinfo --formats确认驱动短名拼写。

从 doc/source/programs/gdal_options/if.rst 这个精简的定义出发，结合 apps/gdalargumentparser.cpp、gcore/gdaldataset.cpp 与 apps/gdalinfo_bin.cpp 的源码，即可完整理解--if从一行命令到驱动级筛选的每一环——这也是排查 GDAL 打开异常时最有价值的排错线索。

• GIS
• 遥感
• 数据工程