简介这是一份面向 GIS 开发初学者与 ArcGIS 桌面用户的 ArcPy 入门教程旨在帮助读者快速掌握用 Python 访问和控制 ArcGIS 的核心工作流适合具备基础 Python 语法、希望实现数据处理与空间分析自动化的人群。资源包为单个 PDF 电子文档整体约 7.76MB内文从环境准备与 import arcpy 导入讲起系统覆盖工具调用、地理处理服务、函数与类、环境设置、消息类型与严重性、错误处理、数据路径设置、许可与扩展模块访问等关键主题并深入介绍了数据集列表创建、多值输入、字段映射、脚本定时运行等实操技能。教程结构清晰章节由浅入深每章辅以示例代码便于边学边练也可作为日常查阅的速查手册。目前已有 468 人浏览学习对于正在入门 ArcPy 或希望提升地理处理效率的 Python 用户是一份值得收藏的基础学习资料。1. 为什么是 ArcPyGIS 批处理的正确打开方式很多后端工程师第一次接触 ArcGIS 时最大的困惑是“为什么不直接写 SQL 改数据库”。你可以用数据库客户端改属性表但空间分析、缓冲区、叠加、几何修复这些操作SQL 帮不了你。ArcPy 是 ArcGIS Desktop 自带的 Python API它把数百个地理处理工具封装成函数和类让 Python 脚本像调用普通函数一样调用 Buffer、Clip、Intersect 这些 GIS 工具。你需要它通常是因为手上有几百个要素类要批量处理或者要做一个每天凌晨跑一次的自动化流程。这份教程用一份老目录当线索把 ArcPy 的基础逻辑讲透从 import 到工具调用再到游标操作、错误处理和批处理技巧。有 Python 基础就能跟着写不需要先成为 GIS 专家。2. 从 import arcpy 到跑通第一个工具环境、参数与常见版本坑2.1 版本差异为什么你的 import 报错import arcpy报 ModuleNotFoundError90% 的情况不是代码问题是解释器选错了。ArcGIS Desktop 10.x 系列内置的是 Python 2.7而 ArcGIS Pro 2.x 使用 Python 3.x 的 conda 环境。同一个环境里通常只有一个 Python 能识别 arcpy 包因为它不是通过 pip 安装的普通库而是随 ArcGIS 安装包注册到特定解释器里的。我一般会先确认目标机器上装了哪个产品。如果是 ArcMap就在它的 Python 窗口里执行 import arcpy或者用桌面安装目录下的 python.exe 跑脚本例如C:\Python27\ArcGIS10.x\python.exe。如果是 ArcGIS Pro就用项目自带的 conda 环境。用系统自带的 Python 或者外接的 Anaconda 去 import大概率失败即使把路径加进 sys.path 也很容易碰到 DLL 加载错误因为底层依赖 native 库。产品Python 版本常用执行入口ArcGIS Desktop 10.x2.7ArcMap 内置 Python 窗口 /C:\Python27\ArcGIS10.x\python.exeArcGIS Pro 2.x3.x按版本不同Pro 内置 Python / conda 环境下的 python.exe注意不要在 ArcGIS Pro 3.x 里直接跑为 10.x 写的脚本旧脚本里的arcpy.mapping在新版本变成了arcpy.mp这种差异比 Python 版本差异更隐蔽。反过来在 Desktop 上跑新脚本会遇到语法不兼容比如 f-string 在 Python 2.7 里直接报错。所以第一步是把运行环境固定下来写脚本时先声明目标环境。2.2 第一个工具调用工具箱别名与参数顺序ArcPy 把工具封装成工具名_工具箱别名的形式。比如 Clip 工具属于 Analysis 工具箱所以完整函数名是arcpy.Clip_analysis。这个命名规则来自工具框的属性不是随便起的。你打开 ArcToolbox 找到某个工具右键属性就能看到工具箱别名Py 脚本里的函数名就是工具名加下划线加别名。import arcpy arcpy.env.workspace rC:\gis_data arcpy.env.overwriteOutput True result arcpy.Clip_analysis( in_featuresroads.shp, clip_featuresboundary.shp, out_feature_classroads_clip.shp, )这里把工作空间设为C:\gis_data之后所有相对路径都基于这个目录解析。overwriteOutput设为 True允许同名输出文件被覆盖。Clip 的四个位置参数按工具对话框从上到下的顺序传用关键字参数能避免记错顺序。工具返回一个Result对象可以用result.getOutput(0)得到输出要素类的路径后面要拿输出结果做下一步操作时很有用。记不住参数顺序时最省事的方法是先在 ArcMap/ArcGIS Pro 里手动跑一次工具打开地理处理结果面板右键复制 Python 片段那段代码就是标准调用方式比自己翻帮助文档快得多。对于复杂的多值参数或者可选参数复制出来的代码会把缺失参数写成#可以直接保留。提示复制 Python 片段时工具会保留绝对路径改成相对路径前先确认 workspace 已经设置否则输出会写到当前进程的工作目录很难找。2.3 环境设置workspace、overwrite 与空间参考环境设置是 ArcPy 脚本里最容易埋坑的部分因为它们都是全局状态。arcpy.env.workspace决定了所有未带绝对路径的输入输出位置arcpy.env.scratchWorkspace则用于临时数据。overwriteOutput默认是 False第二次跑同一条脚本经常因为输出已存在而报错。除了这两个还需要关注空间参考环境。arcpy.env.outputCoordinateSystem可以设置输出数据的坐标系常用的是传一个SpatialReference对象。arcpy.env.XYResolution和XYTolerance影响拓扑容差默认值在小范围高精度数据下可能导致奇怪的几何结果。我一般在脚本开头集中设置一批环境变量方便后面排查。import arcpy arcpy.env.workspace rC:\gis_data\make.gdb arcpy.env.scratchWorkspace rC:\gis_data\scratch.gdb arcpy.env.overwriteOutput True arcpy.env.outputCoordinateSystem arcpy.SpatialReference(3857) arcpy.env.XYTolerance 0.001 MetersSpatialReference(3857)是 Web Mercator 投影的工厂编码常用的还有 4326WGS84 经纬度、3857、2385 等。指定坐标系后输出要素会自动做投影转换省去在每个工具里单独设置输出的麻烦。环境变量作用常见误用workspace默认工作空间路径相对基准忘记设置导致相对路径找不到数据overwriteOutput允许覆盖输出设成 False 后重复执行报错scratchWorkspace中间数据存放位置不设置时临时数据散落在系统临时目录outputCoordinateSystem输出坐标系与输入坐标系不一致时未注意投影转换环境变量是进程级别的脚本里设置会在进程结束前一直生效。如果脚本里要临时切换逻辑可以用with arcpy.EnvManager(workspacer...)进行局部覆盖但 Python 2.7 的旧版 ArcPy 不一定支持10.3 之后的版本才可靠。这里顺手提一句如果发现设置了 workspace 但工具仍然报路径不存在先检查是不是某个参数塞入了绝对路径绝对路径不参与 workspace 解析容易造成“为什么单独这个文件找不到”的错觉。3. 游标才是数据操作的核心SearchCursor 与 UpdateCursor 实战3.1 为什么不用 arcpy.SearchCursor而用 arcpy.da游标是 ArcPy 遍历和修改要素类属性表的基本手段。早期 ArcPy 有 SearchCursor、UpdateCursor、InsertCursor 三个类现在官方推荐使用 arcpy.da 模块下的同名游标。da 版本有多项改进支持 with 上下文管理退出时释放锁可以使用字段名列表代替复杂的字段名对象新增 SHAPE 这样的几何令牌能直接读写几何对象。如果还在用arcpy.SearchCursor(fc)循环里需要cursor.next()操作完还要手动del cursor一旦中途抛异常数据锁很容易残留导致后续工具无法打开同一个要素类。da 游标配合 with 语句不会出现这个问题。我在维护老项目时会把旧游标逐步替换掉改造量不大但稳定性提升明显。3.2 SearchCursor条件过滤与字段选取SearchCursor 用于只读遍历。它有三个常用参数目标要素类、字段列表、可选 where 子句。字段列表里可以混用普通字段名和 SHAPE 这类令牌令牌不在表结构里但可以取出几何对象。import arcpy fc rC:\gis_data\landuse.shp fields [FID, TYPE, SHAPEAREA] with arcpy.da.SearchCursor(fc, fields, where_clauseTYPE forest) as cursor: for row in cursor: print(row[0], row[1], row[2])字段列表对应每行元组的下标顺序。SHAPEAREA返回要素面积相当于自动做了几何计算不需要先把整个几何读出来再取面积速度快很多。where_clause 的语法由数据源决定文件地理数据库里字段名用双引号括起shapefile 里字段名不加引号字符串值使用单引号。跨数据源最稳妥的做法是先在小数据集上测试或者使用arcpy.AddFieldDelimiters来生成正确的字段分隔符。还有一种情况where_clause 里的字段是保留字或含空格。在文件地理数据库中要写成field name value在 shapefile 中则可能直接报 SQL 语法错误。遇到这种数据我一般把AddFieldDelimiters拼进查询语句里避免手工写死。3.3 UpdateCursor批量更新与数据修复UpdateCursor 与 SearchCursor 的遍历方式类似区别是它支持updateRow方法把修改后的行写回。常见用途是批量更新属性、根据几何重新计算面积、清理无效记录。注意更新游标在遍历时锁定数据不要在迭代过程中再打开同一个要素类的另一个编辑游标ArcPy 不保证这种嵌套调用的稳定性。import arcpy fc rC:\gis_data\parcels.shp fields [SHAPE, AREA_CALC, STATUS] with arcpy.da.UpdateCursor(fc, fields) as cursor: for row in cursor: geom row[0] if geom is None: row[2] INVALID else: row[1] round(geom.area, 2) row[2] OK cursor.updateRow(row)这里用SHAPE取出几何对象调用.area得到平面面积。检查geom is None是因为数据里可能存在空几何不做判断直接取面积会抛 TypeError。updateRow接收的元组长度和顺序必须与字段列表完全一致否则会报长度不匹配。如果需要新增要素用 InsertCursor。常见做法是遍历一个点表为每个点生成缓冲区要素或者把外部数据源里的坐标批量插入为点要素。import arcpy fc rC:\gis_data\points.shp fields [SHAPE, NAME] with arcpy.da.InsertCursor(fc, fields) as cursor: points [(120.1, 30.2, A), (120.2, 30.3, B)] for x, y, name in points: pt arcpy.Point(x, y) cursor.insertRow((pt, name))arcpy.Point 是纯坐标对象insertRow 会自动把它构建成点几何。插入大量数据时批量插入比逐条调用工具快得多但要注意一次脚本执行中不要反复打开关闭 InsertCursor最好一次性把所有行写入再提交。游标读/写适用场景关键方法SearchCursor只读条件查询、统计for row 遍历UpdateCursor读改批量更新属性、修复几何cursor.updateRowInsertCursor只写批量插入新要素cursor.insertRow游标处理是 ArcPy 脚本性能差异最大的环节。有些脚本处理几万条记录要几分钟换成 da 游标并减少字段数量后可以降到几秒。后面第 5 章会再展开性能相关的内容。4. 错误不是异常消息机制与脚本健壮性设计4.1 消息类型与严重性ArcGIS 工具运行时会产生三类消息信息、警告、错误对应严重性级别 0、1、2。工具执行完不报错不代表没有警告比如输入坐标系缺失时工具会提示“未知坐标系”但继续运行。如果在脚本里只关注是否抛异常会漏掉这些会导致结果不可信的警告。arcpy.GetMessages(0)返回所有消息GetMessages(1)返回警告GetMessages(2)返回错误。arcpy.GetMessage(i)按索引取单条。输出是字符串可以用splitlines()逐行处理。消息内容通常是英文的在 ArcGIS 中文版界面下也是英文所以脚本日志里最好保留原始消息不要只记录自定义的“成功”。4.2 用 ExecuteError 捕获地理处理失败普通工具失败时ArcPy 会抛出arcpy.ExecuteError这是最典型的异常类型。区别于程序本身的语法错误或 Python 内置异常ExecuteError 表示工具进入了执行阶段但失败了比如输出目录不存在、字段名错误、空间参考不一致等。import arcpy import traceback arcpy.env.workspace rC:\gis_data try: arcpy.Buffer_analysis(roads.shp, roads_buf.shp, 100 Meters) except arcpy.ExecuteError: print(GP Error:, arcpy.GetMessages(2)) except Exception: print(General Error:, traceback.format_exc())这里分开捕获ExecuteError和普通Exception因为两者需要暴露的排错信息不同。ExecuteError 直接用GetMessages(2)取错误消息比 traceback 里的 Python 堆栈更容易定位是哪个工具、哪个参数出了问题。普通异常则用traceback.format_exc()打全堆栈方便查代码本身的逻辑错误。如果脚本里连续跑多个工具只在最后统一捕获异常会很难定位失败源。我一般会在每个工具调用后检查arcpy.GetMessages(1)有警告就打印这样数据异常可以提前暴露。还可以用Result对象的getMessages()方法获取单次工具运行的消息避免多人共用环境时消息被其他工具覆盖。4.3 记录日志让脚本变成可监控的任务脚本一旦进入定时任务控制台输出就没人看了。最简单的做法是把消息写到文件用 Python 标准库 logging 就能实现。要注意的是 logging 默认的编码在 Windows 中文环境下可能输出乱码建议明确 encoding 参数。import logging import arcpy logging.basicConfig( filenamerC:\logs\gp_task.log, levellogging.INFO, format%(asctime)s %(levelname)s %(message)s, encodingutf-8, ) logging.info(task start) try: arcpy.Buffer_analysis(roads.shp, roads_buf.shp, 100 Meters) logging.info(buffer done) except arcpy.ExecuteError as err: logging.error(GP failed: %s, arcpy.GetMessages(2)) raise用 logging 而不是在异常里 print最大的好处是可以按时间戳追溯每次运行。第二次跑脚本时若输出被覆盖日志里保留的时长和参数能帮助判断是数据变了还是代码变了。另外ExecuteWarning是 ExecuteError 的兄弟类在工具产生警告而不是错误时抛出但实际场景里很少依赖它大多用消息级别过滤来处理。5. 把脚本放进生产数据遍历、批量修复与性能边界5.1 用 ListFeatureClasses 遍历工作空间处理多个要素类时不要手写文件列表。arcpy.ListFeatureClasses按工作空间里的数据源返回要素类名配合环境变量 workspace 使用import arcpy arcpy.env.workspace rC:\gis_data\data.gdb for fc in arcpy.ListFeatureClasses(): print(arcpy.Describe(fc).shapeType)Describe可以拿到要素类型、空间参考、字段信息等元数据。这里注意ListFeatureClasses返回的是名称不是完整路径需要先用Describe(fc).path拼接或者直接用工作空间加名称构造路径。用arcpy.da.Walk可以遍历子目录和多个工作空间适合批量整理散落在各处的 shapefile。5.2 批量修复几何一个生产级小工具常见需求是“arcpy 修复几何”通常指RepairGeometry工具。它能把要素类里的空几何、自相交多边形等拓扑错误自动修复但修改前必须备份。常见做法是先把原始数据复制到备份目录再批量处理。import arcpy import shutil import os arcpy.env.workspace rC:\gis_data\data.gdb backup_dir rC:\gis_data\backup for fc in arcpy.ListFeatureClasses(): src os.path.join(arcpy.env.workspace, fc) dst os.path.join(backup_dir, fc _bak.gdb) if not arcpy.Exists(dst): arcpy.Copy_management(src, dst) arcpy.RepairGeometry_management(src)RepairGeometry_management不需要参数表直接对传入要素类原地修复。备份用Copy_management而不是 shutil是因为要素类是地理数据库对象不是普通文件。如果数据量大修复后建议再跑一次 Check Geometry 验证确认错误数量归零。5.3 性能边界与更优方案ArcPy 的基础脚本足够处理几千个要素但超过十万级时逐行游标循环会明显变慢。这时可以考虑三条路少取字段、用 SQL 过滤尽早缩小集合、把纯属性运算放到数据库端执行。比如批量更新面积字段不要在 Python 里做round(geom.area, 2)后一条条 updateRow可以直接用arcpy.CalculateField_management传 SQL 表达式让数据库自己算IO 和锁竞争都会减少。需要大量空间计算时arcpy 还提供 NumPy 集成把要素类读成 structured array用向量化运算代替游标但前提是几何处理可以用数组操作表达否则复杂度不低。da 游标的所有修改是实时写入的没有编辑会话也没有撤销所以批量修复几何或者更新属性前先做备份是生产环境里最值得固化的习惯。本文还有配套的精品资源点击获取