ArcPy脚本运行时如何实时追踪进度？arcpy.AddMessage用法详解（附：效率提升脚本）

wowwwai GIS研习社 · 工具流程与项目排障

在 ArcGIS Pro 或 ArcMap 中运行地理处理脚本时，很多同学都会遇到一个问题：脚本明明还在跑，但界面没有反馈，不知道是卡死了还是正在处理。本文围绕ArcPy脚本运行时如何实时追踪进度？arcpy.AddMessage用法详解（附：效率提升脚本）这个场景，讲清楚如何用 arcpy.AddMessage、arcpy.SetProgressor 和简单的计时逻辑，让 ArcPy 脚本运行过程更透明、更容易排错。

引言：为什么 ArcPy 脚本需要实时追踪进度

ArcPy 脚本常用于批量裁剪、字段计算、空间连接、缓冲区分析、栅格处理等任务。这类任务往往有两个特点：数据量大、运行时间长。如果没有任何进度提示，用户只能盯着 ArcGIS 的运行窗口等待。

实时输出运行信息的价值主要有三点：

• 确认脚本是否真的在运行，而不是卡住或死循环。
• 快速定位脚本在哪一步变慢或报错。
• 在批处理任务中记录已完成数量、当前要素类、耗时等信息。

在 ArcPy 中，最常用的进度反馈方式就是 arcpy.AddMessage。它可以把信息输出到 ArcGIS Pro 的地理处理消息窗口，也可以配合 Python 日志、计时器和进度条使用。

背景：ArcPy 脚本运行时看不到进度的常见原因

很多 ArcPy 初学者会在脚本中使用 print() 输出信息，但在 ArcGIS Pro 的脚本工具中，print() 并不总是以最友好的方式显示。尤其是把 Python 脚本封装成地理处理工具后，更推荐使用 ArcPy 提供的消息函数。

ArcPy 中常见的消息输出函数包括：

• arcpy.AddMessage()：输出普通运行信息，适合显示当前步骤、处理数量、耗时等。
• arcpy.AddWarning()：输出警告信息，适合提示字段缺失、空数据、坐标系不一致等非致命问题。
• arcpy.AddError()：输出错误信息，适合提示脚本无法继续执行的严重问题。

如果脚本只在 Python IDE 中运行，print() 看起来没问题；但如果脚本要发布为 ArcGIS 工具箱工具、分享给同事使用，或者在模型构建器中调用，arcpy.AddMessage 会更稳定、更符合 ArcGIS 地理处理工具的使用习惯。

原理：arcpy.AddMessage 是如何显示运行信息的

arcpy.AddMessage 的作用是向当前地理处理环境写入一条普通消息。它不会改变数据，也不会加快工具本身的计算速度，但可以让用户看到脚本执行到了哪一步。

基本语法很简单：

import arcpy

arcpy.AddMessage("开始执行脚本...")
arcpy.AddMessage("正在读取输入数据")
arcpy.AddMessage("处理完成")

当脚本作为 ArcGIS Pro 的脚本工具运行时，这些信息会显示在工具运行结果的消息窗口中。对于长时间运行的批处理任务，建议在以下位置添加消息：

• 脚本开始运行时。
• 读取输入参数后。
• 每个主要处理步骤开始前。
• 循环处理每个数据集时。
• 输出结果创建完成后。
• 捕获异常并准备退出时。

需要注意的是，arcpy.AddMessage 不是进度条。它负责输出文本消息；如果要显示百分比进度，还应结合 arcpy.SetProgressor 和 arcpy.SetProgressorPosition。

步骤：用 arcpy.AddMessage 实时追踪 ArcPy 脚本进度

步骤一：在脚本开头输出运行环境和输入参数

脚本一开始就输出关键信息，可以帮助你确认脚本读取的参数是否正确。尤其是输入要素类、输出路径、缓冲距离、字段名等，最好都显示出来。

import arcpy
import os
import time

input_fc = arcpy.GetParameterAsText(0)
output_fc = arcpy.GetParameterAsText(1)
buffer_distance = arcpy.GetParameterAsText(2)

start_time = time.time()

arcpy.AddMessage("开始运行 ArcPy 脚本")
arcpy.AddMessage("输入数据: {}".format(input_fc))
arcpy.AddMessage("输出数据: {}".format(output_fc))
arcpy.AddMessage("缓冲距离: {}".format(buffer_distance))

这一步看似简单，但非常实用。很多脚本错误并不是算法问题，而是用户选择了错误的数据、错误的地理数据库路径，或者参数为空。

步骤二：在关键处理步骤前后输出消息

以缓冲区分析为例，可以在执行工具前后分别输出消息，明确当前脚本运行到哪一步。

arcpy.AddMessage("正在执行缓冲区分析...")

arcpy.analysis.Buffer(
    in_features=input_fc,
    out_feature_class=output_fc,
    buffer_distance_or_field=buffer_distance
)

arcpy.AddMessage("缓冲区分析完成: {}".format(output_fc))

如果脚本中有多个工具连续执行，例如投影、裁剪、空间连接、字段计算，建议每个工具前都写一条明确的 arcpy.AddMessage。

步骤三：在循环批处理中显示当前进度

批量处理多个要素类时，最需要实时追踪进度。下面示例会遍历一个工作空间中的所有要素类，并对每个要素类输出处理状态。

import arcpy
import os
import time

workspace = arcpy.GetParameterAsText(0)
output_gdb = arcpy.GetParameterAsText(1)
buffer_distance = arcpy.GetParameterAsText(2)

arcpy.env.workspace = workspace
feature_classes = arcpy.ListFeatureClasses()

if not feature_classes:
    arcpy.AddWarning("当前工作空间中没有找到要素类")
else:
    total = len(feature_classes)
    arcpy.AddMessage("共发现 {} 个要素类，开始批量处理".format(total))

    for index, fc in enumerate(feature_classes, start=1):
        step_start = time.time()

        arcpy.AddMessage("[{}/{}] 正在处理: {}".format(index, total, fc))

        out_name = "{}_buffer".format(os.path.splitext(fc)[0])
        out_fc = os.path.join(output_gdb, out_name)

        arcpy.analysis.Buffer(
            in_features=fc,
            out_feature_class=out_fc,
            buffer_distance_or_field=buffer_distance
        )

        step_seconds = time.time() - step_start
        arcpy.AddMessage("[{}/{}] 完成: {}，耗时 {:.2f} 秒".format(index, total, fc, step_seconds))

这种写法适合批量缓冲、批量裁剪、批量投影、批量转换格式等任务。用户可以清楚看到当前处理的是第几个数据、处理了多久、输出到了哪里。

步骤四：结合 SetProgressor 显示进度条

如果脚本工具在 ArcGIS Pro 中运行，可以使用 arcpy.SetProgressor 创建进度条。arcpy.AddMessage 负责显示文字说明，SetProgressor 负责显示进度。

import arcpy
import os
import time

workspace = arcpy.GetParameterAsText(0)
output_gdb = arcpy.GetParameterAsText(1)
buffer_distance = arcpy.GetParameterAsText(2)

arcpy.env.workspace = workspace
feature_classes = arcpy.ListFeatureClasses()

if not feature_classes:
    arcpy.AddWarning("未找到可处理的要素类")
else:
    total = len(feature_classes)

    arcpy.SetProgressor("step", "正在批量生成缓冲区...", 0, total, 1)
    arcpy.AddMessage("任务总数: {} 个要素类".format(total))

    for index, fc in enumerate(feature_classes, start=1):
        arcpy.SetProgressorLabel("正在处理 {}/{}: {}".format(index, total, fc))
        arcpy.AddMessage("正在处理 {}/{}: {}".format(index, total, fc))

        out_name = "{}_buffer".format(os.path.splitext(fc)[0])
        out_fc = os.path.join(output_gdb, out_name)

        arcpy.analysis.Buffer(fc, out_fc, buffer_distance)

        arcpy.SetProgressorPosition(index)
        arcpy.AddMessage("已完成: {}".format(out_fc))

    arcpy.ResetProgressor()
    arcpy.AddMessage("全部处理完成")

这就是 ArcPy 脚本运行时实时追踪进度的常用组合：arcpy.AddMessage 输出可读信息，SetProgressor 显示任务进度。

步骤五：加入异常捕获，让错误信息更清楚

如果脚本报错但没有清晰提示，用户很难判断问题出在哪里。建议使用 try、except 捕获异常，并输出 ArcPy 工具错误信息。

import arcpy
import traceback

try:
    arcpy.AddMessage("开始执行空间分析任务")

    input_fc = arcpy.GetParameterAsText(0)
    output_fc = arcpy.GetParameterAsText(1)

    arcpy.analysis.Clip(input_fc, arcpy.GetParameterAsText(2), output_fc)

    arcpy.AddMessage("裁剪完成: {}".format(output_fc))

except arcpy.ExecuteError:
    arcpy.AddError("ArcPy 工具执行失败")
    arcpy.AddError(arcpy.GetMessages(2))

except Exception as e:
    arcpy.AddError("Python 脚本运行失败: {}".format(e))
    arcpy.AddError(traceback.format_exc())

arcpy.GetMessages(2) 通常用于获取错误级别的地理处理消息。它比单纯输出 Python 异常更适合排查 ArcGIS 工具执行失败的问题。

步骤六：附一个可复用的效率提升脚本模板

下面这个模板适合批量处理任务。你可以把具体的处理逻辑替换成缓冲区、裁剪、投影、空间连接或字段计算。

import arcpy
import os
import time
import traceback

def log_message(text):
    current_time = time.strftime("%H:%M:%S")
    arcpy.AddMessage("[{}] {}".format(current_time, text))

def safe_name(name):
    base = os.path.splitext(os.path.basename(name))[0]
    return arcpy.ValidateTableName(base)

def main():
    workspace = arcpy.GetParameterAsText(0)
    output_gdb = arcpy.GetParameterAsText(1)
    buffer_distance = arcpy.GetParameterAsText(2)

    arcpy.env.workspace = workspace
    arcpy.env.overwriteOutput = True

    start_time = time.time()

    log_message("开始批量处理")
    log_message("输入工作空间: {}".format(workspace))
    log_message("输出地理数据库: {}".format(output_gdb))

    feature_classes = arcpy.ListFeatureClasses()

    if not feature_classes:
        arcpy.AddWarning("没有找到要素类，脚本结束")
        return

    total = len(feature_classes)
    success_count = 0
    fail_count = 0

    arcpy.SetProgressor("step", "正在批量处理要素类...", 0, total, 1)

    for index, fc in enumerate(feature_classes, start=1):
        try:
            step_start = time.time()
            arcpy.SetProgressorLabel("正在处理 {}/{}: {}".format(index, total, fc))
            log_message("开始处理 {}/{}: {}".format(index, total, fc))

            out_name = "{}_buffer".format(safe_name(fc))
            out_fc = os.path.join(output_gdb, out_name)

            arcpy.analysis.Buffer(
                in_features=fc,
                out_feature_class=out_fc,
                buffer_distance_or_field=buffer_distance
            )

            success_count += 1
            step_seconds = time.time() - step_start
            log_message("完成: {}，耗时 {:.2f} 秒".format(out_fc, step_seconds))

        except arcpy.ExecuteError:
            fail_count += 1
            arcpy.AddWarning("处理失败: {}".format(fc))
            arcpy.AddWarning(arcpy.GetMessages(2))

        except Exception as e:
            fail_count += 1
            arcpy.AddWarning("处理失败: {}".format(fc))
            arcpy.AddWarning(str(e))

        finally:
            arcpy.SetProgressorPosition(index)

    arcpy.ResetProgressor()

    total_seconds = time.time() - start_time
    log_message("批处理结束")
    log_message("成功: {}，失败: {}，总耗时 {:.2f} 秒".format(success_count, fail_count, total_seconds))

if __name__ == "__main__":
    try:
        main()
    except Exception:
        arcpy.AddError("脚本发生未处理异常")
        arcpy.AddError(traceback.format_exc())

这个脚本模板的重点不是缓冲区本身，而是把进度追踪、耗时统计、异常捕获和输出命名统一放进一个可复用结构中。实际项目中，你只需要替换中间的地理处理工具即可。

常见坑：使用 arcpy.AddMessage 时容易忽略的问题

1. 只在脚本结束时输出消息

如果只在最后写一句“处理完成”，运行过程中用户仍然不知道脚本是否卡住。建议在耗时步骤前后都输出 arcpy.AddMessage，尤其是循环处理和大数据分析。

2. 消息过于模糊

不要只写“正在处理”。更好的写法是说明当前处理对象、总数、输出路径和耗时。

arcpy.AddMessage("正在处理 {}/{}: {}".format(index, total, fc))

3. 在循环中输出过于频繁

如果按每一个要素输出一条消息，几十万条要素会产生大量日志，反而拖慢脚本。对于要素级循环，建议每处理 1000 条或 5000 条输出一次。

if count % 1000 == 0:
    arcpy.AddMessage("已处理 {} 条要素".format(count))

4. 把 AddMessage 当成性能优化工具

arcpy.AddMessage 只能帮助观察进度，不能直接提高空间分析速度。真正影响效率的因素包括数据格式、空间索引、坐标系、字段数量、磁盘读写、临时数据位置和工具参数。

5. 忽略 AddWarning 和 AddError

普通消息、警告、错误应该分开使用。比如数据为空但脚本还能继续，可以用 arcpy.AddWarning；输出路径不存在导致脚本无法继续，应使用 arcpy.AddError 并终止流程。

方法比较：print、arcpy.AddMessage、logging 该怎么选

如果脚本主要在 ArcGIS Pro 中作为工具运行，优先使用 arcpy.AddMessage。如果脚本同时需要保存运行记录，可以把 arcpy.AddMessage 和 Python 的 logging 结合起来。

检查清单：发布 ArcPy 脚本工具前建议确认这些项

• 脚本第一段是否输出了输入参数和输出路径。
• 每个耗时的地理处理工具前后是否有 arcpy.AddMessage。
• 批处理循环中是否显示当前序号和总数。
• 是否使用 arcpy.SetProgressor 显示进度条。
• 是否用 arcpy.AddWarning 提示可跳过的问题。
• 是否用 arcpy.AddError 输出致命错误。
• 是否捕获了 arcpy.ExecuteError 并输出 arcpy.GetMessages(2)。
• 是否统计了总耗时和每个步骤耗时。
• 是否避免在大量要素循环中逐条输出消息。
• 输出名称是否经过合法性处理，避免特殊字符导致失败。

FAQ：ArcPy脚本运行时追踪进度常见问题

1. arcpy.AddMessage 和 print 有什么区别？

print 更适合普通 Python 控制台调试，arcpy.AddMessage 更适合 ArcGIS Pro 或 ArcMap 的地理处理工具消息窗口。如果脚本要给 GIS 用户通过工具箱运行，建议使用 arcpy.AddMessage。

2. arcpy.AddMessage 能显示百分比进度吗？

arcpy.AddMessage 本身只输出文本消息。要显示进度条，应结合 arcpy.SetProgressor、arcpy.SetProgressorLabel 和 arcpy.SetProgressorPosition。

3. 为什么我的 AddMessage 没有实时显示？

可能与运行环境、工具执行方式、界面刷新机制有关。一般来说，在 ArcGIS 脚本工具中运行时，消息会显示在地理处理结果窗口中。对于单个长时间运行的 ArcGIS 工具，消息可能要等工具返回后才集中显示，这时可以在工具前后增加更明确的步骤提示。

4. 在 ArcPy 循环中多久输出一次消息比较合适？

如果是按数据集循环，可以每个数据集输出一次。如果是按要素循环，不建议每条要素都输出，通常每 1000 条、5000 条或按百分比节点输出一次更合适。

5. AddMessage 会不会影响脚本运行速度？

少量消息影响很小。但如果在大循环中频繁输出，例如几十万次 arcpy.AddMessage，会明显增加消息写入开销。进度追踪要适度，建议输出关键节点，而不是输出每一个对象。

6. ArcPy 批处理脚本如何记录失败的数据？

可以在 except 中把失败的数据名称加入列表，最后统一输出。对于需要长期追踪的任务，还可以写入文本日志或 CSV 文件。

failed_items = []

try:
    arcpy.analysis.Buffer(fc, out_fc, buffer_distance)
except Exception:
    failed_items.append(fc)
    arcpy.AddWarning("处理失败: {}".format(fc))

if failed_items:
    arcpy.AddWarning("以下数据处理失败: {}".format(", ".join(failed_items)))

结论：用 AddMessage 让 ArcPy 脚本更可控

ArcPy脚本运行时实时追踪进度，并不只是为了“看起来更专业”，而是为了让脚本更容易调试、更容易交付、更适合真实 GIS 项目中的批量处理任务。

推荐的实践方式是：用 arcpy.AddMessage 输出关键步骤，用 arcpy.SetProgressor 显示批处理进度，用 time 统计耗时，用 try 和 except 处理错误。这样写出来的 ArcPy 脚本，即使面对大量数据和长时间任务，也能让用户清楚知道脚本正在做什么、做到哪里、哪里出了问题。

如果你正在把 Python 脚本封装成 ArcGIS Pro 脚本工具，建议把本文中的效率提升脚本模板作为基础框架，再根据你的具体空间分析流程替换中间的处理逻辑。