ArcGIS的ModelBuilder迭代输出命名用 %Name%：output_%Name% 每轮唯一，避免新结果覆盖旧结果

一、问题现场：为什么迭代结果总是“只剩最后一个”

先还原一个几乎每个 GIS 从业者都遇到过的场景。你有一个县级行政区划面图层，想按每个县裁剪一份土地利用栅格；或者你有一批 CSV 点位文件，想逐个转成要素类并做缓冲区。于是你打开 ModelBuilder，拖入“迭代要素类”或“迭代文件”迭代器，接上裁剪工具，指定输出路径为 D:\out\clip_result.shp，运行。模型跑完，打开输出目录，只有一个文件。你以为是工具没执行，其实它执行了 N 次，只是每次都写进了同一个文件。

这个现象的机制并不复杂。在 ModelBuilder 的数据流中，迭代器负责在每一轮循环里把“当前元素”暴露为一个模型变量。以“迭代要素类”为例，它会输出两个可用变量：一个是要素类的完整路径，通常命名为“要素类”或 %FeatureClass%；另一个是当前要素类的名称，即 %Name%。如果你在输出路径里只写了固定字符串，那么这个路径在每一轮都是常量，ArcGIS 会忠实地覆盖它。

本文评述：很多人把这个问题归咎于“ModelBuilder 不好用”，但笔者认为它恰恰暴露了一个更普遍的数据工程常识——循环体内的输出标识必须随循环变量变化。这在 Python 里是 for name in names: open(f"out_{name}.txt","w") 的常识，在 ModelBuilder 里则表现为行内变量的显式引用。工具本身没有错，错的是把“循环”当成了“批处理”的直觉。

从数据管理角度看，覆盖式输出带来的损失是多层的。第一层是数据丢失：前面 N-1 轮的计算资源被浪费，且无法恢复。第二层是可追溯性断裂：你无法回答“第 7 个县的裁剪结果长什么样”。第三层是并行与中断风险：如果模型中途失败，你甚至无法判断哪些输入已经处理过。Esri 官方文档在介绍迭代器时反复强调“迭代器会为每个元素运行一次模型”，但并未把“输出命名”作为强制约束，这给初学者留下了认知缺口。

值得注意的是，覆盖行为在不同输出类型下表现并不一致。要素类、栅格数据集、表格通常会被直接覆盖；而文件夹、地理数据库中的要素数据集则可能因为命名冲突报错而非静默覆盖。这种不一致性进一步加剧了排查难度。笔者认为，理解这一点的关键在于区分“物理存储路径”与“逻辑数据集名称”——前者是操作系统层面的文件，后者是地理数据库层面的对象，二者的冲突策略并不相同。

二、%Name% 是什么：行内变量替换的机制与作用域

2.1 行内变量的基本语法

ModelBuilder 支持一种轻量的字符串替换语法：用百分号包裹变量名，形如 %变量名%。当模型运行时，引擎会在参数求值阶段把这些占位符替换为变量的当前值。这个机制被称为“行内变量替换”（inline variable substitution），它并非 ModelBuilder 独有，在 ArcGIS 的许多工具参数、路径表达式、SQL 表达式中都能见到。

以迭代要素类为例，迭代器暴露的变量通常包括：%Name%（不含扩展名的名称）、%FeatureClass%（完整路径）、有时还有 %Workspace%（所在工作空间）。不同迭代器暴露的变量名不同：迭代栅格暴露 %Raster% 与 %Name%，迭代文件暴露 %File% 与 %Name%，迭代行则暴露字段名对应的变量。

表 1：常见迭代器暴露的变量对照（依据 Esri ArcGIS Pro 帮助文档“Iterate tools”章节整理，2024）。

2.2 作用域：变量在哪里可见

行内变量并非全局可见。它的作用域严格限定在“迭代器下游”的模型元素中。也就是说，只有直接或间接连接到迭代器输出变量的工具，才能在其参数里引用 %Name%。如果你在迭代器上游写 %Name%，模型校验阶段就会报“变量未定义”或直接把它当普通字符串处理。

这个作用域规则带来两个实践后果。其一，输出路径参数必须位于迭代器下游，通常就是迭代器直接驱动的那个工具。其二，如果你用了“子模型”或“模型内嵌”，变量需要显式传递，否则子模型内部看不到父模型的迭代变量。Esri 的“模型构建器变量传递”文档对此有说明，但在实际项目中，子模型变量丢失是仅次于覆盖问题的第二大坑。

笔者认为：把行内变量理解为“循环体的局部变量”是最贴切的类比。它随迭代轮次变化，只在循环体内有效，循环体外引用就是未定义行为。建立这个心智模型后，很多“为什么我的 %Name% 不生效”的问题会迎刃而解。

2.3 替换发生的时机

行内变量替换发生在参数求值阶段，而不是工具执行阶段。这意味着替换后的字符串会作为最终参数传给底层地理处理工具。理解这一点对调试很重要：如果替换结果包含非法字符，报错会出现在工具执行时，而不是替换时。你看到的错误信息往往是“路径无效”或“数据集名称非法”，而不是“变量替换失败”。

此外，替换是纯字符串层面的，不做任何转义或清洗。如果 %Name% 的值里含有空格、连字符、中文或点号，它们会被原样拼进路径。这就是为什么“迭代要素类”遇到名为“XX 县-2020”的图层时，输出路径可能直接失效。关于这一点，第五节会展开。

三、命名唯一性的三种实现路径与对比

让每轮输出唯一，本质上是要让输出标识成为迭代变量的函数。在 ModelBuilder 里，至少有三条路径可以实现，各有适用边界。

3.1 路径一：输出路径内联 %Name%

最直接的做法，是在输出参数的路径字符串里嵌入 %Name%。例如把输出写成 D:\out\clip_%Name%.shp。当迭代到“A县”时，实际输出为 D:\out\clip_A县.shp；迭代到“B县”时，输出为 D:\out\clip_B县.shp。每轮路径不同，自然不会覆盖。

操作步骤并不复杂：在 ModelBuilder 中双击目标工具打开参数面板，找到输出参数，点击输入框右侧的下拉箭头，选择“模型变量”或直接手动输入带百分号的字符串。较新版本的 ArcGIS Pro 会在你输入 % 时自动提示可用变量，这是比 ArcMap 时代更友好的体验。

3.2 路径二：输出到独立工作空间

如果每轮输出都放进不同的地理数据库或文件夹，即使数据集名称相同也不会冲突。例如用 D:\out\%Name%\result.shp，让每个迭代元素拥有自己的目录。这种做法的好处是结构清晰，便于按元素归档；代价是目录数量可能爆炸，且部分工具对动态工作空间的支持不如动态数据集名稳定。

3.3 路径三：用计算值工具生成名称

当命名逻辑更复杂时，比如需要拼接前缀、时间戳、序号，或对 %Name% 做清洗，可以插入“计算值”（Calculate Value）工具。它允许你用 Python 表达式生成一个字符串变量，再把这个变量接到输出路径。例如表达式 "clip_" + re.sub(r"[^0-9A-Za-z]", "_", "%Name%") 可以把非法字符替换为下划线。

表 2：三种命名唯一化路径的对比（笔者基于 ArcGIS Pro 3.x 实践整理）。

本文评述：三种路径并非互斥。在真实项目里，笔者通常采用“内联 %Name% + 计算值清洗”的组合：先用计算值把名称规范化，再把规范化后的变量内联进输出路径。这样既保留了简单性，又规避了非法字符风险。选择哪种路径，取决于输入数据的命名质量和输出管理的粒度需求。

四、实战：批量裁剪、投影、栅格统计的命名模板

理论说清楚后，落到具体场景。下面给出三个高频任务的完整操作路径，命名模板可以直接复用。

4.1 场景一：按行政区批量裁剪栅格

输入：一个土地利用栅格 landuse.tif，一个县级行政区面图层 counties.shp。目标：每个县裁剪一份栅格，输出到 D:\out\。

模型结构：迭代要素类（输入 counties.shp）→ 按掩膜提取（Extract by Mask）→ 输出。关键在“按掩膜提取”的输出参数，写成 D:\out\landuse_%Name%.tif。迭代到“A县”时输出 landuse_A县.tif，迭代到“B县”时输出 landuse_B县.tif。

这里有一个细节：迭代要素类的 %Name% 取的是要素类名称，而不是某个字段值。如果你希望输出名来自“县名”字段而非图层名，需要改用“迭代行”或“迭代要素选择”，让变量绑定到字段值。这是初学者常混淆的一点。

4.2 场景二：批量投影转换

输入：一个文件夹下若干 Shapefile，坐标系各异。目标：统一投影到 CGCS2000，输出到地理数据库。

模型结构：迭代要素类（输入文件夹）→ 投影（Project）→ 输出。输出参数写成 D:\out.gdb\proj_%Name%。注意地理数据库内的要素类名称不能带扩展名，所以这里不要写 .shp。如果输入文件名本身带 .shp，迭代器的 %Name% 通常已去掉扩展名，但不同版本行为略有差异，建议先用“计算值”确认一次。

4.3 场景三：批量栅格统计

输入：一个文件夹下若干栅格。目标：对每个栅格计算分区统计或全局统计，输出为 CSV 或表格。

模型结构：迭代栅格 → 分区统计（Zonal Statistics as Table）或“获取栅格属性”→ 输出表。输出参数写成 D:\out\stats_%Name%.csv。如果输出到地理数据库，写成 D:\out.gdb\stats_%Name%。

# 等价 ArcPy 写法（供对照）
import arcpy, os
arcpy.env.workspace = r"D:\raster_in"
out_ws = r"D:\out.gdb"
for rst in arcpy.ListRasters():
    name = os.path.splitext(rst)[0]
    out_tab = os.path.join(out_ws, "stats_" + name)
    arcpy.sa.ZonalStatisticsAsTable("zones", "zone_id", rst, out_tab, "DATA", "ALL")

这段脚本与模型等价，但把命名逻辑显式化了。笔者建议，凡是用 ModelBuilder 跑通流程后，如果迭代次数超过几十次，或需要更复杂的名称清洗，就应迁移到 ArcPy。模型适合搭原型，脚本适合上生产。

五、常见陷阱：非法字符、扩展名、路径长度与中文名

5.1 非法字符

Shapefile 和地理数据库对名称字符有不同限制。Shapefile 名称不能含空格、连字符、点号（除扩展名外），且长度受限；文件地理数据库允许更多字符，但仍不建议使用特殊符号。当 %Name% 来自真实数据时，名称里出现“XX-2020”“XX 县”的概率很高，直接内联就会踩坑。

解决方案是用“计算值”做清洗。一个稳健的表达式是：re.sub(r"[^0-9A-Za-z_\u4e00-\u9fa5]", "_", "%Name%")。它保留字母、数字、下划线和常用汉字，其余替换为下划线。注意，如果目标数据库对中文支持不佳，还应进一步转拼音或哈希。

5.2 扩展名重复

如果 %Name% 已包含扩展名，而你在输出路径里又写了 .shp，就会得到 clip_A.shp.shp 这类畸形名称。不同迭代器对扩展名的处理不一致：迭代文件通常保留扩展名，迭代要素类通常去掉。最稳妥的做法是先用“计算值”把 %Name% 打印出来看一眼，再决定是否拼接扩展名。

5.3 路径长度

Windows 传统路径上限为 260 字符。当输出目录层级深、名称长时，拼接 %Name% 后很容易超限。表现是工具报“路径过长”或静默失败。缓解办法包括：缩短输出根目录、使用地理数据库而非多级文件夹、对长名称做截断或哈希。ArcGIS Pro 在较新版本中对长路径的支持有所改善，但底层仍受操作系统约束。

5.4 中文名与编码

中文名称在 Shapefile 中可能因编码问题显示为乱码，在地理数据库中通常正常。如果必须用中文名，建议输出到文件地理数据库，并确保模型运行环境的区域设置一致。笔者在实践中倾向于把中文名转写为拼音或英文缩写，牺牲一点可读性换取跨平台稳定性。

笔者认为：命名唯一性只是第一步，命名“可移植性”才是工程化的更高要求。一个只在你自己机器上跑得通的命名方案，换一台机器、换一个数据库就可能崩溃。把名称清洗成保守字符集，是低成本高回报的防御性设计。

六、从模型到脚本：ArcPy 中的等价写法与增强

ModelBuilder 的 %Name% 替换，在 ArcPy 中对应的是显式的字符串拼接。理解二者的映射关系，有助于在模型和脚本之间自由切换。

6.1 基本映射

模型里的“迭代要素类 + 裁剪 + output_%Name%”，在 ArcPy 中就是遍历 arcpy.ListFeatureClasses()，对每个要素类调用 arcpy.Clip_analysis()，输出路径用 os.path.join(out_ws, "clip_" + name) 拼接。脚本的优势在于：可以加异常处理、可以记录日志、可以做更复杂的名称清洗。

6.2 增强：日志与断点续跑

脚本可以轻松实现“已存在则跳过”，从而支持断点续跑。例如在循环开头判断 arcpy.Exists(out_fc)，若存在则 continue。这在处理上千个要素时非常实用，因为一次失败不必从头再来。ModelBuilder 也能通过“如果数据存在”逻辑实现类似效果，但配置起来比脚本繁琐。

import arcpy, os, re, logging
logging.basicConfig(filename="clip.log", level=logging.INFO)

arcpy.env.workspace = r"D:\counties"
out_ws = r"D:\out.gdb"
clip_fc = r"D:\study_area.shp"

for fc in arcpy.ListFeatureClasses():
    name = re.sub(r"[^0-9A-Za-z_\u4e00-\u9fa5]", "_", os.path.splitext(fc)[0])
    out_fc = os.path.join(out_ws, "clip_" + name)
    if arcpy.Exists(out_fc):
        logging.info("skip existing: %s", out_fc)
        continue
    try:
        arcpy.Clip_analysis(fc, clip_fc, out_fc)
        logging.info("done: %s", out_fc)
    except Exception as e:
        logging.error("fail %s: %s", fc, e)

这段代码把“命名唯一”和“运行可追溯”结合了起来。日志文件记录了每个输出的生成时间与状态，配合唯一命名，就构成了一条完整的处理链证据。Esri 的 ArcPy 文档对 ListFeatureClasses、Exists 等函数有详细说明，建议结合官方示例阅读。

6.3 从脚本回到模型：Python 工具箱

如果你既想要脚本的灵活性，又想在 ModelBuilder 里调用，可以把脚本封装成 Python 工具箱（.pyt）。这样模型里就能像调用普通工具一样调用你的脚本，参数通过工具对话框传入。命名逻辑封装在脚本内部，模型层面只需关心输入输出。这是 Esri 推荐的“模型 + 脚本”混合工作流。

七、工程化延伸：任务链、日志与可复现性设计

把视野再拉高一层。命名唯一性不只是“不覆盖”，它是可复现性设计的一个环节。一个可复现的地理处理流程，至少需要三样东西：确定的输入、确定的参数、确定的输出标识。唯一命名保证了第三样。

7.1 任务链中的命名传递

在 ArcGIS Pro 的任务（Tasks）或工作流管理器（Workflow Manager）中，一个任务可能包含多个步骤。如果每个步骤都产生中间数据，命名需要在整个链路上保持唯一且可关联。常见做法是用“业务主键 + 步骤标识 + 时间戳”组成名称，例如 A县_clip_20240115。这样即使中间结果很多，也能通过名称回溯到源头。

7.2 元数据与溯源

唯一命名配合元数据，可以回答“这个结果从哪来”。ArcGIS 支持在输出数据上写入元数据，记录工具、参数、时间。如果名称里已经包含了输入标识，溯源会更直观。笔者认为，对于需要长期维护的数据产品，命名规范应当作为数据标准的一部分被文档化，而不是留给每个操作者自由发挥。

7.3 并行与冲突

如果多个模型实例并行运行，即使各自内部命名唯一，跨实例仍可能冲突。解决办法是给每个实例分配独立的工作空间或名称前缀。例如用进程 ID 或时间戳作为前缀。这一点在服务器端批量任务中尤其重要。

本文评述：%Name% 是一个很小的语法点，但它牵出的是数据工程中“标识管理”的大问题。从文件命名到数据库主键，从日志追踪到版本控制，底层逻辑是一致的：让每个产物有唯一且可推导的身份。ModelBuilder 把这个逻辑以最朴素的方式呈现了出来。

八、前沿观察与结语

近年来，地理处理正在从桌面工具向云端、向自动化流水线迁移。ArcGIS Pro 的模型可以发布为 Web 工具，在 ArcGIS Enterprise 或 ArcGIS Online 上运行；开源侧则有 QGIS Processing 框架、GDAL/OGR 命令行、Snakemake/Nextflow 等工作流引擎。在这些环境里，“每轮输出唯一”依然是刚需，只是实现方式从 %Name% 变成了模板字符串、通配符或参数化路径。

笔者认为，未来值得关注的方向有三个。其一，基于内容哈希的自动命名，让输出名直接反映输入与参数的指纹，从根本上杜绝冲突并支持去重。其二，声明式工作流中的命名推导，由引擎根据依赖关系自动生成唯一标识，用户不再手写名称。其三，与数据湖、对象存储的结合，命名规则需要适配扁平化、高并发的存储语义。

回到最初的问题：output_%Name% 之所以有效，是因为它把“循环变量”显式地写进了“输出标识”。这是一个简单到容易被忽视的动作，却是批量地理处理从“能跑”走向“可靠”的分水岭。掌握它，不需要高深理论，只需要理解变量作用域和字符串替换这两件小事。但正是这些小事，决定了你的模型是玩具还是工具。

最后补充几个延伸学习入口。Esri 官方帮助文档的“ModelBuilder 中的迭代”与“行内变量替换”章节是最权威的起点；YouTube 上 Esri 官方频道有 ModelBuilder 迭代器的实操演示；国内方面，ArcGIS 知乎专栏、CSDN 的 GIS 板块有大量中文案例，但质量参差，建议以官方文档为准。开源方向可参考 QGIS 的“Graphical Modeler”文档与 GDAL 的 gdalwarp 批量脚本示例。

主要参考文献