将ArcPy脚本封装为工具箱工具
将 ArcPy 脚本封装为工具箱工具,主要有两种正规方式:在自定义工具箱(推荐 .atbx)里新建脚本工具,或直接创建 Python 工具箱(.pyt)。封装后的工具外观、运行方式与系统地理处理工具一致,可在目录窗格打开、放入 ModelBuilder、被其他脚本调用,并写入地理处理历史。新手优先用脚本工具;需要大量自定义参数验证时,再考虑 Python 工具箱。

脚本工具和 Python 工具箱怎么选
两者都能把你的 ArcPy 逻辑变成可复用工具,差别主要在参数定义方式和维护成本。脚本工具用属性对话框配置参数,源代码通常放在单独的 .py 文件里,适合先写好脚本再“挂”到工具箱。Python 工具箱把工具箱类、参数、验证和执行代码全部写在一个 .pyt 文件中,更利于版本控制和复杂校验,但对 Python 类结构更熟悉。
| 对比项 | 脚本工具(.atbx / 旧 .tbx) | Python 工具箱(.pyt) |
|---|---|---|
| 参数定义 | 工具属性对话框(向导) | 代码里用 arcpy.Parameter |
| 源代码位置 | 外部 .py,或嵌入工具 | 全部在 .pyt 中 |
| 验证逻辑 | 可选 Validation 页 / 脚本 | updateParameters、updateMessages 等方法 |
| 适合谁 | 新手、脚本已写好、参数相对固定 | 需复杂联动验证、重视纯文本版本管理 |
| 其他类型工具 | 同一工具箱还可放模型工具等 | 本身是代码工具箱,可调用其他工具箱中的工具 |
截至 2026 年 11 月,ArcGIS Pro 从 3.0 起已不能在工程里新建旧版 .tbx,推荐使用 .atbx(自 2.9 引入,跨版本兼容与持久性更好)。旧版 ArcMap 相关流程已退役,新项目一律按 Pro 与 .atbx / .pyt 来做。更细的对比可参考 Esri 官方说明:自定义工具箱与 Python 工具箱对比。
如何把现有 ArcPy 脚本做成脚本工具
目标很明确:让同事在工具对话框里填参数就能跑,而不是打开 Python 窗口粘代码。按下面步骤在 ArcGIS Pro 中操作即可。
- 在目录窗格中,右键“工具箱”→ 新建工具箱,选择 ArcGIS 工具箱(.atbx),放到工程文件夹或共享路径下。
- 右键该工具箱 → 新建 → 脚本,打开工具属性对话框。
- 在 General 页填写:名称(仅字母数字下划线)、标签(可含空格,显示给用户)、描述。名称不要用中文或空格。
- 在 Parameters 页按顺序添加参数:每个参数指定显示名称、数据类型、类型(必选/可选)、方向(输入/输出)。至少要有一个输出参数,否则难以在 ModelBuilder 中串联。
- 在 Execution 页指定脚本:指向外部 .py,或直接把代码嵌入。分享给他人时,建议嵌入脚本(Import Script),避免路径丢失。
- 需要时在 Validation 页写校验逻辑(如根据输入图层自动过滤字段列表)。保存后,在地理处理窗格中打开工具试跑。
官方逐步说明见:Adding a script tool(添加脚本工具)。创建完成后,工具会出现在工具箱中,用法与系统工具相同。

脚本里怎样正确获取参数并写出结果
封装的关键是:对话框里的参数顺序与脚本读取索引一致。推荐用 arcpy.GetParameterAsText(index) 取文本形式参数(无长度限制),或用 arcpy.GetParameter(index) 取对象类型;索引从 0 开始,与 Parameters 列表顺序一一对应。尽量少用 sys.argv,它有长度限制且不适合复杂类型。
典型写法要点:
- 输入要素类、字段、工作空间等,按你在对话框中定义的顺序用 GetParameterAsText 取出。
- 环境设置可直接用 arcpy.env(如 overwriteOutput、scratchWorkspace),工具运行时 ArcPy 会感知当前工程环境。
- 必须把最终结果写到“输出”参数对应的路径或数据集上;可用 arcpy.SetParameterAsText 或 SetParameter 把结果回传给对话框/ModelBuilder。
- 用 arcpy.AddMessage、AddWarning、AddError 写进度与诊断信息,用户才能在工具消息窗口看到,而不是只在你本地的 print 里。
验收标准:在工具对话框中填好参数后能成功运行;地理处理历史里有记录;把输出拖进地图或接到下一个模型工具时路径正确;改一个可选参数后行为符合预期。
路径、分享和加密要注意什么
最常见翻车点是脚本路径。相对路径在工具箱或脚本被移动后容易失效,典型报错是“与此工具关联的脚本不存在”(错误 000576)。处理办法:
- 右键工具 → 属性,检查 Execution / Source 中的脚本路径是否仍有效。
- 分享前优先把脚本导入工具(显示为 <<Imported>>),或保持 .atbx 与 .py 相对目录不变并一起打包。
- .atbx 本身更利于跨版本携带;若必须用旧 .tbx,注意相对路径选项,但新项目不要再新建 .tbx。
- 需要保护源码时,脚本工具可嵌入并设置密码保护;Python 工具箱可对 .pyt 加密。以当前 Pro 版本界面操作为准。
若要把一整套工具作为模块分发,还可进一步做成地理处理 Python 包(含消息与帮助),那是工具箱之上的扩展方式,适合团队内部统一发布,而不是单次脚本封装。
常见问题
脚本工具和直接在 Python 窗口跑脚本有什么实质区别?
窗口跑脚本适合调试;封装成工具后,参数有对话框、能进 ModelBuilder、写入地理处理历史、可被其他工具调用,同事无需改代码即可复用,这才是“工具箱工具”的价值。
Parameters 里一定要设输出参数吗?
是的。没有输出参数时,工具很难在 ModelBuilder 中作为下游输入,也无法规范地回传结果路径。即使脚本只是改属性或写日志,也应定义一个输出(例如输出要素类、表或派生参数)。
出现错误 000576 怎么办?
几乎都是脚本路径失效。打开工具属性核对脚本位置;分享时改为嵌入脚本,或保证工具箱与 .py 相对位置不变。修好路径后重新打开工具再运行。
该用 .atbx 还是 .pyt?我已经有一个能跑的 .py 了。
已有独立 .py、参数不复杂:用 .atbx 新建脚本工具最快。若参数会互相联动、校验很多、又希望整个工具箱都是纯文本便于 Git:新建 .pyt,把逻辑迁进去。
把 ArcPy 脚本封装为 arcpy 脚本工具,核心是选对载体(新手用 .atbx 脚本工具)、参数顺序与 GetParameterAsText 对齐,并保证至少有一个输出参数。先做一次本地试跑和路径检查,再决定是否嵌入源码用于分享;需要复杂验证时再转到 Python 工具箱,避免一开始就把简单脚本写得过重。