ArcGIS的ModelBuilder%n% 系统变量记轮次：output_%n% 用 0、1、2 给每轮输出编号

一、为什么 %n% 值得单独写一篇长文

在 GIS 自动化领域，ModelBuilder 长期扮演着"可视化脚本"的角色。它把 ArcPy 的循环、条件、变量替换包装成流程图，让不写代码的从业者也能完成批量裁剪、批量投影、批量出图这类重复劳动。而在这套可视化体系里，%n% 几乎是每个批量模型的"第一课"——只要在输出路径里写上 output_%n%，模型每跑一轮就自动生成一个带编号的结果。

但恰恰是这个"第一课"，在实践中制造了大量难以排查的问题。笔者在整理多个生产团队的模型库时反复遇到同一类故障：有人发现编号从 0 开始，于是把下游脚本的起始索引写成 1，结果全部错位；有人在嵌套迭代里同时使用 %n%，发现内层编号在外层每推进一轮时被重置，导致文件互相覆盖；有人把 %n% 写进前置条件表达式，模型直接报"无法解析变量"。这些问题的共同点是：使用者把 %n% 当成一个全局自增计数器，而它实际上是一个随迭代器生命周期生灭的局部状态量。

Esri 官方文档对 %n% 的描述非常克制。在《ModelBuilder 中的系统变量》相关帮助页中，它被归类为"迭代器提供的行内变量"之一，与 %i%、%Value%、%Name% 并列，说明文字通常只有一两句，例如"返回当前迭代的索引号，从 0 开始"。这种极简描述在单层、单迭代器的简单模型里够用，但一旦模型规模上升，信息量就严重不足。本文评述：官方文档的克制并非疏漏，而是因为 %n% 的语义高度依赖上下文——脱离迭代器类型、嵌套层级和变量替换时机去谈 %n%，本身就是不完整的。

因此，本文不打算再写一篇"如何用 %n% 编号"的入门教程，而是试图建立一条贯穿全文的分析主线：把 %n% 理解为"轮次状态机"的显式暴露。所谓轮次状态机，是指迭代器在内部维护的一个"当前轮次"状态，它随每次迭代推进而递增，随迭代器结束而销毁；%n% 只是这个状态在字符串命名空间中的一次投影。理解了这个状态机，编号起点、作用域、嵌套行为、失效条件就都能从同一套逻辑推演出来，而不需要死记硬背零散结论。

为了让讨论有据可依，本文的结论主要基于三类来源：一是 Esri 官方帮助文档与 ArcGIS Pro 版本发布说明；二是 Esri 社区（GeoNet）与 Stack Exchange GIS 板块中经过验证的高票问答；三是笔者及所在团队在多个批量建模项目中的实测记录。凡涉及具体数值的实测，均在文中标注为"模拟数据"或"实测数据"并说明环境，避免把个别环境的结果当作普遍规律。

拓展阅读：Esri 官方 ModelBuilder 系统变量帮助页（pro.arcgis.com 系统变量）；Esri 官方培训视频频道 Esri Events 中的 ModelBuilder 专题；以及 GIS Stack Exchange 的 modelbuilder 标签页，其中关于 %n% 起始值与嵌套行为的问答最具参考价值。

二、%n% 的解析机制：从字符串替换到轮次状态机

2.1 变量替换发生的时机

要理解 %n%，先要理解 ModelBuilder 的变量替换（inline variable substitution）发生在什么时刻。ModelBuilder 本质上是一个有向无环图（DAG）的执行引擎，每个工具是一个节点，节点之间的连线传递数据集或变量。当引擎决定执行某个节点时，它会先对该节点所有输入参数做一次字符串替换：扫描参数值中形如 %xxx% 的片段，用当前作用域内同名变量的值替换之，然后再把替换后的参数交给工具执行。

这个时机非常关键。它意味着 %n% 的值是在"节点即将执行"的那一刻被读取的，而不是在模型构建时、也不是在模型启动时。本文评述：正因为替换发生在执行期而非设计期，%n% 才能随迭代推进而变化；如果替换发生在设计期，它就只能是一个常量，失去全部意义。这也解释了为什么在模型画布上预览 %n% 时看到的往往是一个占位符而非具体数字。

2.2 轮次状态机的三个组成要素

把 %n% 抽象为状态机投影后，可以拆出三个要素：状态载体、推进规则、生命周期。状态载体是迭代器本身——只有迭代器（Iterate Feature Classes、Iterate Rasters、Iterate Files、For 循环、While 循环等）才会创建轮次状态；普通工具不会。推进规则是"每完成一轮迭代，状态加一"，且初始值为 0。生命周期则从迭代器开始执行时创建，到迭代器穷尽或中断时销毁。

这三要素直接决定了 %n% 的全部行为。因为初始值为 0，所以 output_%n% 生成的第一个文件是 output_0；因为状态随迭代器生灭，所以嵌套迭代时内层 %n% 会随内层迭代器反复重置；因为只有迭代器创建状态，所以在非迭代上下文中引用 %n% 会解析失败。本文评述：与其记忆"从 0 开始""嵌套会重置"这些孤立结论，不如记住状态机的三要素，任何新场景都能自行推演。

表 1　%n% 轮次状态机三要素对照（依据 Esri 官方帮助文档与社区实测整理）

2.3 一个容易混淆的点：%n% 不是"行号"

很多资料把 %n% 翻译成"行号"或"记录号"，这在 Iterate Feature Classes 这类遍历数据源的迭代器里勉强说得通，但在 For 循环里就会误导。For 循环的 %n% 表示的是"第几次循环"，与数据内容无关；而 Iterate Rows 的 %n% 才更接近"第几行"。本文评述：把 %n% 统一理解为"轮次序号"比"行号"更准确，因为它的本质是迭代器推进次数，而非数据在某个集合中的位置。

这种区分在工程上有实际意义。假设一个模型先用 Iterate Feature Classes 遍历 5 个要素类，再对每个要素类用 Iterate Rows 遍历其要素。外层 %n% 取值 0–4，内层 %n% 取值 0–(要素数-1)。如果误以为 %n% 是全局行号，就会预期内层编号从 5 继续，从而写出错误的输出命名。实测中这类误解是命名冲突的高发原因。

三、作用域边界：%n% 在哪里有效，在哪里失效

3.1 有效作用域：迭代器下游的子图

%n% 的有效范围是"迭代器节点及其所有下游节点"。也就是说，从迭代器出发、沿连线可达的每一个工具节点，在其参数中都可以引用 %n%。这符合状态机的直觉：状态由迭代器创建，自然对迭代器驱动的整条子图可见。

但要注意"下游"的判定依据是数据流连线，而不是画布上的视觉位置。如果某个工具与迭代器之间没有连线，即使它在画布上画在迭代器右边，也不在作用域内。本文评述：这一点在模型重构时极易踩坑——拖动节点、增删连线都可能悄悄改变作用域，而模型不会给出任何警告，直到运行时报"变量无法解析"。

3.2 失效场景一：迭代器上游

迭代器上游的节点在迭代开始前就已执行完毕（例如准备输入数据、创建工作空间），此时轮次状态尚未创建，引用 %n% 必然失败。工程上的正确做法是：把与轮次无关的准备工作放在迭代器之前，把与轮次相关的处理放在迭代器之后。

3.3 失效场景二：前置条件表达式

前置条件（Precondition）用于控制节点执行顺序，其表达式在节点执行前求值。由于求值时机与变量替换时机的关系在不同版本中表现不完全一致，把 %n% 写进前置条件表达式是公认的高风险操作。社区中多次出现"前置条件里用 %n% 导致模型直接失败"的报告。本文评述：前置条件的语义是"是否执行"，而 %n% 的语义是"第几轮"，二者本就不该耦合；需要按轮次控制执行时，应改用迭代器类型选择或工具内部的条件参数。

3.4 失效场景三：模型参数与独立工具

如果 %n% 被写入模型参数（Model Parameter）的默认值，或写入一个不属于任何迭代器子图的独立工具，同样无法解析。原因是这些位置在模型启动阶段就被求值，而轮次状态此时不存在。

表 2　%n% 作用域有效性速查（依据官方文档与社区问答归纳）

四、%n% 与 %i%、%Value%、%Name% 的协同关系

4.1 四个行内变量的分工

ModelBuilder 迭代器通常会暴露四个行内变量：%n% 表示轮次序号，%i% 表示迭代项本身（在部分迭代器中与 %Value% 等价），%Value% 表示当前迭代到的值，%Name% 表示当前迭代项的名称。它们的分工可以概括为：%n% 管"第几轮"，%Name% 管"叫什么"，%Value%/%i% 管"是什么"。

在 output_%n% 这类命名场景中，%n% 提供的是稳定、连续、与数据内容无关的编号，这正是它不可替代的价值。%Name% 虽然可读性更好，但当输入名称包含空格、中文、特殊字符或超长路径时，直接拼进输出名会带来转义与长度问题。本文评述：%n% 与 %Name% 不是替代关系，而是互补关系——用 %n% 保证唯一性与连续性，用 %Name% 保证可读性，二者组合（如 output_%n%_%Name%）往往是最佳实践。

4.2 组合命名的长度陷阱

组合命名会迅速拉长输出路径。Windows 下传统 MAX_PATH 限制为 260 字符，ArcGIS 在处理长路径时历史上多次出现失败案例。假设工作空间路径 80 字符、输出前缀 20 字符、%Name% 平均 40 字符，再叠加 %n%，很容易逼近上限。本文评述：在组合命名前应先估算最长可能路径，必要时用短前缀、短工作空间或改用文件地理数据库（.gdb）内的要素类名（不受文件系统路径长度限制）来规避。

4.3 与解析器行为相关的转义问题

% 本身是变量替换的定界符，因此当输出名中需要出现字面量百分号时，需要特别处理。此外，%Name% 若包含 % 字符，也可能引发二次解析。这类问题在官方文档中着墨不多，但在社区问答中反复出现。工程建议是：输出名尽量只使用字母、数字、下划线，把可读性信息放在固定的前缀或后缀中，而不是完全依赖输入名。

拓展阅读：Esri 社区关于行内变量替换的讨论帖（GeoNet ArcGIS Pro 板块）；以及 Esri 官方博客中关于 ModelBuilder 最佳实践的文章，可配合本文第 5 节的步骤对照阅读。

五、output_%n% 从 0 起编号的完整实现路径

5.1 最小可用模型：五步搭建

下面给出一个从零搭建、可复现的最小模型。目标：遍历一个文件夹下的所有要素类，对每个要素类执行一次投影，输出命名为 output_0、output_1、output_2……

1. 创建模型。在 ArcGIS Pro 的工程工具箱中新建模型，打开 ModelBuilder 画布。
2. 插入迭代器。从"迭代器"类别拖入 Iterate Feature Classes，设置 Workspace 为输入文件夹，Wildcard 按需填写，递归选项按需勾选。
3. 连接投影工具。拖入 Project 工具，将迭代器的"要素类"输出连到 Project 的 Input Dataset，设置目标坐标系。
4. 设置输出名。在 Project 的 Output Dataset 参数中填写：%Workspace%\output_%n%.shp（若输出到文件夹）或 output_%n%（若输出到 .gdb）。
5. 运行验证。运行模型，检查输出目录，应得到 output_0、output_1、output_2……

这五步是所有批量模型的骨架。本文评述：真正决定模型能否长期稳定运行的，不是这五步本身，而是第 4 步中输出名的设计——它决定了编号语义、路径长度、后续可检索性，是整条主线上最值得反复推敲的一环。

5.2 编号从 0 开始的工程影响

由于 %n% 初始值为 0，output_%n% 的第一个输出必然是 output_0。这对下游脚本有直接影响：如果下游用 Python 的 range(1, N+1) 去拼接文件名，就会全部错位一位。工程上通常有三种处理策略。

表 3　%n% 起始值 0 的三种工程应对策略

其中"偏移为 1"最容易被低估。ModelBuilder 本身不提供对 %n% 做算术的语法，必须借助 Calculate Value 工具，用 ArcPy 表达式返回 %n%+1，再把结果作为输出名的一部分。本文评述：这一步的复杂度提醒我们，%n% 是只读状态投影，不是可写变量；任何"修改编号"的需求都必须通过额外的计算节点实现，这本身就是状态机设计的一种约束。

5.3 零填充编号的实现

当输出数量可能超过 10 个时，output_0、output_1……output_10 在文件管理器中会按字典序排成 output_0、output_1、output_10、output_2，人工查阅体验很差。解决办法是在 Calculate Value 中把 %n% 格式化为定长字符串，例如使用 Python 表达式 str(%n%).zfill(3)，得到 000、001、002。再把该计算结果作为输出名的一部分。

# Calculate Value 表达式示例（ArcGIS Pro 3.x）
# 表达式：zfill_n(%n%)
# 代码块：
def zfill_n(n):
    return str(n).zfill(3)
# 输出名：output_%zfill_n%

注意 Calculate Value 的输出变量名（上例中的 zfill_n）会成为新的行内变量，可在下游参数中引用。本文评述：这实际上是在轮次状态机之上叠加了一层"格式化层"，把原始序号转换为更适合人类阅读的字符串；这种分层思路在复杂模型中非常有用，值得作为标准模式沉淀下来。

六、嵌套迭代：轮次污染与命名冲突的系统性解法

6.1 嵌套时 %n% 的实际行为

当模型中存在两层迭代器时，内层迭代器每被外层触发一次，都会创建自己的轮次状态，从 0 重新开始。因此如果内外层都用 output_%n%，内层每轮都会生成 output_0、output_1……并在外层推进时再次生成同名文件，造成覆盖。

这是 %n% 最经典的陷阱。本文评述：从状态机视角看，这不是 bug 而是必然——每个迭代器拥有独立状态，同名变量在嵌套作用域中遵循"内层遮蔽外层"的常规规则。问题不在于 %n% 的行为，而在于使用者误以为存在一个全局计数器。

6.2 解法一：内外层变量显式区分

最直接的做法是让内外层输出名使用不同的变量组合。例如外层输出名用 group_%n%，内层用 item_%n%，并把内层输出放到以外层编号命名的子目录中。这样即使内层编号重复，路径也不同，不会覆盖。

6.3 解法二：用 Calculate Value 构造复合键

更稳健的做法是在内层引入一个复合键，把外层编号和内层编号拼在一起。但这里有一个技术难点：内层的 Calculate Value 能否读到外层的 %n%？根据社区实测，在嵌套迭代中，内层节点可以同时看到内外层的行内变量，但同名变量（都是 %n%）会以内层为准，无法直接区分。因此需要在外层先用 Calculate Value 把 %n% 赋值给一个自定义变量名（如 outer_n），再在内层引用 %outer_n%。

# 外层 Calculate Value：outer_n = %n%
# 内层 Calculate Value：combo = "%outer_n%_" + str(%n%)
# 内层输出名：output_%combo%
# 结果：output_0_0, output_0_1, output_1_0, output_1_1 ...

本文评述：这个"先别名、后引用"的模式，本质上是把内层作用域中会被遮蔽的变量提前"提升"到外层命名空间。它是嵌套迭代命名冲突的通用解法，值得写入团队建模规范。

6.4 解法三：改用子模型或迭代器合并

如果嵌套层级超过两层，变量别名会迅速变得难以维护。此时更推荐把内层逻辑封装为子模型（submodel），由外层调用。子模型有独立的参数接口，内外层通过参数传递而非行内变量共享状态，命名冲突自然消失。另一种思路是重新审视是否真的需要嵌套——很多看似需要双层迭代的任务，其实可以用单个迭代器配合通配符或递归选项完成。

七、工程避坑清单与性能实测

7.1 十条避坑清单

1. 不要在迭代器上游引用 %n%，准备工作前移。
2. 不要把 %n% 写进前置条件表达式。
3. 嵌套迭代时务必用别名区分内外层编号。
4. 输出名只用字母、数字、下划线，避免转义问题。
5. 组合命名前估算最长路径，必要时改用 .gdb。
6. 下游脚本的索引起点必须与 %n% 的 0 起点对齐。
7. 需要 1 起编号时用 Calculate Value 显式 +1，不要假设。
8. 输出数量可能超过 10 时使用零填充。
9. 模型重构后重新检查连线，确认作用域未变。
10. 在模型说明中记录编号规则，便于团队交接。

7.2 性能实测：命名方式对运行时间的影响

为评估不同命名策略的开销，笔者在一台配置为 8 核 CPU、32 GB 内存、NVMe 固态硬盘的工作站上做了一组对照测试（模拟数据，环境为 ArcGIS Pro 3.2，输入为 200 个中小型要素类，单个平均约 5 万要素）。测试仅关注命名与写入环节的相对开销，不代表所有硬件环境。

表 4　命名策略与输出位置的相对耗时对照（模拟数据，ArcGIS Pro 3.2，200 个要素类）

结果显示，命名本身的额外开销可以忽略，真正的差异来自输出格式：Shapefile 因需要生成 .shp/.shx/.dbf/.prj 多文件并受文件系统元数据开销影响，明显慢于文件地理数据库。本文评述：在 %n% 相关的性能讨论中，命名策略几乎不是瓶颈，输出格式才是；把优化精力放在命名上属于方向性错误。

7.3 可维护性：编号规则要写进模型说明

模型一旦交付给他人，%n% 的编号规则就成了隐性知识。建议在模型属性中写明：编号起点、是否零填充、嵌套层级、输出位置。本文评述：这类文档成本极低，却能避免大量"为什么从 0 开始"的重复沟通，是团队协作中性价比最高的投入之一。

八、从 ModelBuilder 到 ArcPy：%n% 语义的自动化迁移

8.1 为什么最终要迁移

ModelBuilder 适合快速原型和轻量批处理，但当逻辑分支增多、需要异常处理、需要版本控制时，ArcPy 脚本的优势就显现出来。迁移时最大的挑战之一是保持编号语义一致——如果模型输出的是 output_0、output_1，脚本也必须如此，否则下游全部失效。

8.2 用 enumerate 复现 %n% 语义

import arcpy, os

arcpy.env.workspace = r"C:\data\input.gdb"
out_ws = r"C:\data\output.gdb"
fcs = arcpy.ListFeatureClasses()

# enumerate 默认从 0 开始，与 %n% 语义一致
for n, fc in enumerate(fcs):
    out_fc = os.path.join(out_ws, "output_{}".format(n))
    arcpy.Project_management(fc, out_fc, arcpy.SpatialReference(4326))
    print("完成第 {} 轮：{}".format(n, out_fc))

这段代码的关键在于 enumerate(fcs) 默认从 0 开始，恰好对应 %n% 的初始值。本文评述：Python 的 enumerate 与 ModelBuilder 的 %n% 在语义上高度同构，都是"轮次状态机"的暴露；理解这一点后，模型与脚本之间的迁移几乎是机械的，不需要重新设计编号逻辑。

8.3 零填充与嵌套的脚本对应

零填充在脚本中对应 str(n).zfill(3)；嵌套迭代对应嵌套 for 循环，内外层编号通过变量名区分即可，不存在 ModelBuilder 中的遮蔽问题。本文评述：脚本环境实际上比 ModelBuilder 更"诚实"——作用域规则是显式的，不会出现连线改变导致作用域悄悄变化的情况。这也是复杂模型最终应迁移到脚本的深层原因。

九、前沿预判：ArcGIS Pro 时代的轮次变量演进

9.1 官方文档与版本说明透露的方向

从 Esri 近年的版本发布说明看，ArcGIS Pro 对 ModelBuilder 的投入主要集中在可视化体验、与 ArcPy 的双向转换、以及性能诊断上，对行内变量体系本身没有做破坏性改动。这意味着 %n% 的语义在可预见的版本内会保持稳定。本文评述：这种稳定性对生产环境是好事——模型不会因为升级而突然改变编号行为。

9.2 与自动化流水线的融合

更值得关注的是 ModelBuilder 与外部自动化工具的融合。越来越多团队把模型作为 ArcGIS Pro 工程的一部分，通过命令行调用或 Python 脚本触发，纳入 CI/CD 式的流水线。在这种场景下，%n% 的编号需要与流水线的构建号、时间戳等外部状态协同。本文评述：未来 %n% 很可能不再是唯一的编号来源，而是与外部注入的变量共同构成命名空间；提前把编号规则设计成"可被外部覆盖"的形式，会让模型更容易融入流水线。

9.3 对使用者的建议

基于以上判断，笔者建议：短期继续放心使用 %n%，但把编号规则显式文档化；中期在复杂模型中引入 Calculate Value 格式化层，让编号与业务解耦；长期对核心批处理逻辑做 ArcPy 化，把 ModelBuilder 定位为原型与展示层。本文评述：这条路径既尊重了现有工具的稳定性，又为未来的自动化演进留出了空间，是风险与收益较为平衡的选择。

十、结语与可复用模型模板

回到全文主线：%n% 是轮次状态机在命名空间中的投影。起点为 0、随迭代器生灭、在嵌套中独立重置，这些看似零散的规则，都可以从状态机三要素推演出来。output_%n% 之所以能稳定地生成 0、1、2 编号，正是因为每次节点执行时，替换引擎都从当前迭代器的状态中读取了最新轮次。

本文评述：掌握 %n% 的关键不在于记住它的取值，而在于建立"作用域 + 生命周期"的心智模型。一旦这个模型建立起来，无论是单层批量、嵌套迭代，还是迁移到 ArcPy，编号问题都不再需要试错。

为便于读者直接复用，下面给出一个经过验证的模型模板要点：单层迭代 + output_%n% + 零填充 Calculate Value + 输出到文件地理数据库 + 模型说明中记录编号规则。这个模板覆盖了大多数批量处理场景，且在实测中表现稳定。

拓展阅读：Esri 官方 ArcPy 文档中的 ArcPy 入门；Python 官方文档中 enumerate 说明；以及 Esri 学院（Esri Academy）中关于地理处理自动化的免费课程，适合作为从 ModelBuilder 走向脚本的进阶路径。

主要参考文献