如果你在UiPath流程里处理过那种套了三层的嵌套JSON应该能理解我当时想把电脑砸了的冲动——选择器定位还算简单真正要命的是那几个字符串拆分表达式正则写了一行又一行勉强能跑一换数据格式就全面翻车。后来在一个订单汇总项目里我改成直接在UiPath里调用Python脚本用pandas做数据清洗和聚合整个流程的改造量从预计两天压缩到两个小时。这篇文章围绕“在UiPath中调用Python代码”这件事把选型逻辑、环境配置、核心活动用法、参数传递规则、实战案例和踩坑记录全部拆开讲。适合两类人一类是刚接触UiPath、想把Python能力引进来做数据处理的新人另一类是已经用UiPath做了几个流程、但总觉得在流程里写复杂逻辑特别别扭的开发者。UiPath是业务流程自动化的调度中枢Python是数据处理和算法生态的集合体两者配合得好不好关键看你怎么定义它们的边界。下面这些内容不是我翻文档抄出来的都是从实际项目里一点点验证、踩坑之后沉淀下来的做法。你想复现的话照着一步步来即可。1. 怎么想什么场景才值得把Python拉进UiPath流程1.1 两种工具的能力边界先说结论UiPath和Python不是替代关系是互补关系。UiPath的核心优势在和界面、系统、桌面应用打交道。登录系统、点击按钮、读取网页表格、收发带附件的邮件、按状态机做重试和异常处理这些是它的主场。它的表达式和活动编排能力可以做简单数据加工但一旦涉及复杂的嵌套结构、批量计算、字符串深度清洗代码量会迅速爆炸而且维护成本高得吓人。Python的核心优势则在于数据处理、算法实现、机器学习和第三方库生态。pandas处理几十万行Excel毫无压力json库解析多层嵌套JSON就是几行代码的事更不用提sckit-learn、onnxruntime这些UiPath完全替代不了的算法库。1.2 五个“该让Python干活”的典型场景我在项目里遇到过这么几类情况基本都能对号入座Excel/CSV大批量数据清洗和透视。用UiPath的Excel活动打开大文件性能会明显变慢单元格逐行操作更是痛苦。换成Python的pandas读取、清洗、分组、汇总一次性完成。多层嵌套JSON/XML解析。UiPath的JObject和XDocument能解析但取深层字段时表达式又长又难调试。Python里json库配合递归或pandas的json_normalize几行代码搞定。复杂加密与签名算法。部分企业的接口要求自定义签名规则用UiPath表达式实现过于绕Python里往往有现成库或者几行就能写完。第三方SDK或模型推理。OCR、NLP、机器学习模型推理Python的生态最全UiPath想直接调用基本不可能。正则、编码、文本批量处理。这类脏活累活UiPath也能做但可读性和维护性都很差放进Python函数清晰得多。1.3 三条调用路径怎么选在决定用官方活动包之前我其实试过好几种方案各有各的问题。方案实现方式可维护性调试难度适用情况纯UiPath原生活动字符串处理、Excel活动硬写简单场景尚可复杂逻辑维护成本极高相对直观逻辑简单、数据量小Shell/批处理调用python.exe用Start Process启动进程传参靠命令行脚本和流程分离参数传递僵硬出错后定位困难临时脚本、临时需求UiPath.Python.Activities官方活动包Load Python Script Invoke Python Method原生集成支持参数和返回值可实例化类活动内报错日志可直接看正式集成场景长期维护最终我选择官方活动包原因很直接它能传参、能拿返回值、能实例化Python类并且UiPath官方在持续维护。命令行调用看起来轻巧但参数一多转义、路径、编码问题能把人逼疯。2. 怎么搭解释器、活动包与最小连通性验证2.1 版本匹配与解释器安装Python的版本差异是第一个坑而且是最容易忽略的坑。活动包对Python版本有要求我当时用的Python 3.9非常稳3.10和3.11在较新版本的活动包里也能正常工作。如果你拿不准装3.9最稳妥。安装Python时有个细节容易被忽略不要装Windows商店版Python。那个版本被安装在隐藏的系统目录下路径权限都有问题后续配置UiPath连接非常折腾。去官方网站下载安装包安装时勾选“Add Python to PATH”选项可以省掉很多麻烦。装完之后在命令行工具里敲一行命令确认解释器路径where.exe python能看到明确路径才算装好。如果这里就已经找不到别急着去UiPath里折腾先把系统环境理顺。2.2 系统环境还是虚拟环境对单个流程来说直接用系统Python环境没有任何问题。但如果你手上有多个流程每个流程用的Python包版本还不一样那就必须引入虚拟环境隔离。在系统环境里直接pip install的结果就是A流程升级了某个库B流程突然跑不起来。虚拟环境就是为了终结这种混乱。我的建议是每个正式项目都独立建一个虚拟环境把依赖项通过requirements.txt固定下来python -m venv venv venv\Scripts\activate pip install -r requirements.txt注意一个关键点虚拟环境不可移植。它内部的路径是绝对路径你把这个venv文件夹拷到另一台机器上解释器路径全部失效。后面排错章节我再细说这个坑。2.3 安装活动包与最小连通验证在UiPath的“管理包”窗口里搜索“UiPath.Python.Activities”安装一个稳定版本。装完之后你会在活动面板里看到Load Python Script、Invoke Python Method这两个核心活动。先别急着上业务做一个最小连通性测试。准备一个hello.py文件def say_hello(name): return hello name然后在UiPath里创建Sequence依次放三个活动Load Python ScriptFilePath指向hello.py。Invoke Python MethodMethodName填say_helloInputArguments里传入你的名字变量。Message Box把上一步的返回值直接显示出来。如果这一步能跑通说明你的环境已经通了后面所有复杂调用都是在这个骨架上加东西。如果这一步就报错先回头检查解释器路径再看UiPath进程有没有在环境变量修改后重启过。3. 怎么用加载、调用、传参与取回的四步拆解3.1 Load Python Script加载与执行是两回事很多新人会误解Load Python Script这个活动的含义。它只是把Python文件读入UiPath进程的内存里方便后续Invoke方法直接调用。它不会执行脚本里的函数除非你勾选了属性面板里的“Execute Complete Script”选项。这个“完整执行”选项什么时候用当你的Python脚本顶层有全局语句时比如初始化连接、读取配置文件、加载模型就可以勾选它让脚本在加载阶段就把准备工作做掉。注意不要在循环里反复执行Load。Python解释器的启动有开销反复Load脚本意味着反复初始化解释器你的流程会莫名其妙慢好几倍。正确做法是在流程最前面Load一次后面循环里只做Invoke。3.2 Invoke Python Method参数怎么给、结果怎么接这是最常用的活动。你要做的就是在属性面板里指定MethodNamePython函数名。InputArguments要传的参数按Python函数定义的顺序排列。Result接返回值的变量。传递参数时最常见的方式是用new Object(){arg1, arg2}这种.NET数组表达式。假如你有一个Python函数是这么写的def combine_and_upper(a, b): return f{a} {b}.upper()那么在UiPath侧InputArguments里填new Object(){in_arg1, in_arg2}in_arg1和in_arg2是两个字符串变量。返回值存进一个字符串变量后直接就能用。这里最难记住的点是参数顺序就是Python函数定义的顺序和参数名无关。UiPath没有“按名传参”的机制全部按位置来。写参数时务必对着Python源码看一遍。3.3 实例化Python类处理带状态的场景如果你的Python脚本里封装了类想调用的是类的实例方法那就要在Load阶段做额外配置。比如你在脚本里定义了一个计数器class OrderCounter: def __init__(self): self.count 0 def add(self, amount): self.count amount return self.count此时Load Python Script活动的属性里有两个关键配置Target Object Type选Class。Instance Name给这个类一个实例名比如my_counter。之后Invoke Python Method的TargetObject属性里选择这个实例名MethodName填add就能保持类的内部状态。这个能力在Python类需要维护连接池、缓存、计数器等场景下非常有用。如果Python类里的方法是静态方法不需要实例状态那就不需要Instance Name直接指定类名调用即可。3.4 参数映射与返回值处理的核心原则UiPath和Python之间的数据类型自动转换是有边界的。基础类型基本没问题复杂结构就悬了。我整理了一个速查表UiPath数据类型Python对应类型稳定性Int32 / Int64int稳定Doublefloat稳定Stringstr稳定Booleanbool稳定Array / Listlist不稳定Dictionarydict不稳定DataTable无直接对应不稳定JObject无直接对应不稳定对于列表、字典这种复杂结构不要裸传。UiPath传过去的列表可能变成Python的list也可能在特定版本里变成其他类型行为不可控。我的做法是“JSON握手协议”任何复杂数据都在一侧序列化成JSON字符串另一侧再反序列化回来。举例Python侧返回一个字典时import json def get_summary(): data {total: 100, regions: [east, west]} return json.dumps(data, ensure_asciiFalse)UiPath侧接收字符串后用Deserialize Json活动转成JObject再按字段取值。反过来传参也一样UiPath侧把对象序列化成JSON字符串Python函数里用json.loads还原。加了个ensure_asciiFalse是防止中文字符被转成Unicode转义序列。这个“JSON握手”方案唯一缺点是每个函数多写两行转换代码但换来的是跨版本稳定性和我夜里能安心睡觉。4. 实战一个让pandas接管Excel处理的完整流程4.1 业务背景与控制边界某公司每天要从ERP系统导出一张订单明细表包含订单号、区域、客户名称、金额、备注等列。麻烦点在于金额列偶尔会出现空白或脏字符区域列里夹杂着前后空格备注列更是格式混乱。需求是要清洗数据后统计各区域销售额Top3并生成一张汇总Excel最后通过邮件发送给业务方。这个流程里UI操作登录ERP、下载文件、发送邮件由UiPath负责数据清洗和统计全部下沉给Python。控制边界很清晰UiPath管界面Python管数据。4.2 Python脚本的职责设计脚本文件process_orders.py定义了一个函数import pandas as pd def process_orders(input_path, output_path): df pd.read_excel(input_path) # 金额列转数值遇到脏字符变成NaN df[amount] pd.to_numeric(df[amount], errorscoerce) # 丢弃金额为空的记录 df df.dropna(subset[amount]) # 区域列清理前后空格 df[region] df[region].str.strip() # 按区域汇总销售额取前三 summary df.groupby(region)[amount].sum().nlargest(3).reset_index() summary.columns [region, total_amount] # 输出汇总表 summary.to_excel(output_path, indexFalse) return fprocessed {len(df)} rows注意几个设计决策errorscoerce让金额列的脏字符转成NaN而不是抛异常流程更健壮。dropna直接过滤掉金额为空的记录这部分数据如果马上发邮件告知业务方方便他们补录。函数只接收两个文件路径不接收DataFrame因为UiPath侧构造DataFrame很麻烦传路径最省事。返回值是一段简单的处理汇总UiPath侧可以直接记录到日志。4.3 UiPath侧的完整流程编排整个Sequence大致长这样从配置文件读取python_script_path、input_excel_path、output_excel_path三个变量。Load Python Script加载process_orders.pyTarget Object Type选Module。Invoke Python Method调用process_ordersInputArguments按顺序传入输入路径和输出路径返回值存到str_result变量。Log Message记录str_result然后检查输出文件是否存在。用Send Email活动把汇总表通过邮件发给业务方。开发阶段可以直接写死路径测试部署阶段请务必把路径改成从配置文件或Orchestrator资产读取。路径一旦写死在流程里换一台机器就是一场灾难。4.4 异常处理与结果回传Python脚本运行过程中可能抛异常——输入Excel不存在、数据格式完全不对、磁盘写入失败。UiPath侧必须能感知并处理。最直接的做法是用Try Catch包裹Invoke活动Catch里读取异常消息发一段告警邮件出来。但这种方式拿到的错误信息比较粗糙不知道到底是清洗阶段出错还是写入阶段出错。更精细的做法是让Python函数返回一个结构化结果。比如def process_orders(input_path, output_path): try: ... return json.dumps({success: True, message: processed 100 rows}) except Exception as e: return json.dumps({success: False, error: str(e)})UiPath侧Deserialize Json后检查success字段是True还是False分别走不同分支。这样做的好处是业务流程对异常的感知更细可以在UiPath侧做精确的重试或者人工介入提示。我在实际项目中用的就是这个方案跑了大半年没有出过状况。5. 排错五次真实接入失败背后的排查链路这一章的价值在于还原排查过程。每个坑我都不直接给答案而是按检查顺序讲一遍。5.1 “找不到解释器”——可能不是路径问题而是启动顺序问题现象是Invoke Python Method直接报错提示类似找不到Python解释器或PythonPath未设置。当时我的第一反应是去活动属性里填PythonPath。填完还是报错再查才知道UiPath进程在启动时就去读取系统环境变量里的Python路径配置这个读取动作只发生一次。你改完环境变量、装好Python之后必须重启UiPath Studio旧进程里读到的还是老环境。排查顺序应该是命令行里执行where.exe python确认解释器确实存在。找到UiPath的Python活动属性显式指定python.exe的绝对路径。重启UiPath Studio后再跑一次。如果用的系统Python还要小心一个问题多个Python解释器共存时“where.exe python”返回的不一定是你要的那个。这时候需要用到py -0列出所有已安装的Python版本再决定指向哪个。5.2 中文参数乱码——先分清是活动编码问题还是文件编码问题有一回给Python函数传中文参数本意是传一个客户名称进去做筛选。结果函数返回的结果里这个中文字段变成了“锟斤拷”这类乱码。排查链路要分两层先看参数传递阶段是否已乱码再看Python侧处理文件时的编码是否有问题。我当时的做法是在Python函数第一行就打印参数和类型def filter_by_name(name): print(name, type(name))日志显示传进去的时候就乱码了说明是UiPath活动包往Python传参时编码转换出问题。解决办法有两个找到活动属性里的Encoding/UTF-8选项改成UTF-8。新版本活动包这里已经默认统一了老版本未必。走Base64绕行UiPath侧先Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes(in_name))Python侧拿到Base64字符串后解码还原。这个方案绕过了所有编码争执兼容性极好。如果日志显示传参正常但Python读文件后中文乱码那就是文件读写编码问题。打开文件时显式加encodingutf-8基本能解决。5.3 装了多个Python版本UiPath连错解释器一个项目用Python 3.8另一个项目用Python 3.10的同事在同一台机器上都配好了环境。结果UiPath加载脚本时报错——ModuleNotFoundError说你那个库没装在当前解释器里。排查时先确定一件事UiPath当前用的到底是哪个解释器。在活动属性里手动指定PythonPath是最稳的方式。不要依赖系统PATH的“默认命中”因为PATH里的顺序可以很混乱UiPath取到的不一定是你想的那个。更隐蔽的情况是你指定了虚拟环境里的python.exe但这个venv是用旧版本Python创建的依赖包也是旧的。用venv\Scripts\python.exe --version和pip list就能快速确认环境对不对。记住UiPath活动里指定的路径要是Python解释器本身而不是脚本目录。5.4 虚拟环境换台机器就罢工本地开发一切正常流程发布到机器人服务器上之后所有Python调用全部报ModuleNotFoundError。最开始我以为是机器人机器上没装依赖去手动安装装完还是不行。最后打开venv目录下的pyvenv.cfg文件才发现问题虚拟环境的配置里写死了开发机的路径整个文件夹拷过去之后解释器路径全部失效。虚拟环境本质上是不可移植的。正确做法是把requirements.txt带到目标机器重新创建venv并安装依赖。如果有条件更推荐用活动包自带的远程执行能力在一台统一管理的机器上维护Python环境多个机器人通过服务方式调用。这样既不要求每台机器装Python也彻底规避了环境漂移问题。5.5 明明有返回值UiPath却拿到空/None这个现象比较诡异Python函数里明明写了returnUiPath这边的变量却是空字符串或者空对象。一个很隐蔽的原因是Python函数实际返回了None。比如代码路径走到了异常分支函数没有走正常return路径UiPath侧接到的就是None。另一个常见原因是UiPath变量类型和返回值不匹配比如方法返回float但Result变量声明成了String导致转换失败被吞掉。我的经验是开发期间不要偷懒Python函数的开头和中间都要加print或日志输出UiPath侧Invoke之后再用Log Message把Result打出来。一旦发现Result为空先看Python侧日志里到底走到了哪条分支基本上一眼就能定位问题。返回复杂对象前先用json.dumps确保序列化成功宁可多一步转换也不要让UiPath去猜类型。6. 进化让Python调用更稳定、更省心的几个习惯6.1 脚本路径不要写死在流程里我见过很多项目的Python脚本路径直接写在Invoke活动的FilePath属性里比如C:\Users\xxx\Documents\script.py。这种写法在开发机上没问题但部署到其他机器人时一定会挂。正确做法是把脚本路径放到UiPath配置文件中用变量读取后传给Load活动。脚本本身建议统一放在流程项目目录下的Scripts子文件夹里这样整个流程打包迁移时脚本能跟着走而不用额外同步文件。6.2 大数据量处理时的性能取舍Python启动解释器有固定的开销一次调用耗时通常在几百毫秒到一两秒。这意味着不要在循环里反复Load Python Script。把Load放到循环外面。循环逻辑尽量写进Python函数里。如果要对1000个文件做处理传一个目录让Python循环扫描远比在UiPath里循环1000次调用Python高效。大批量Excel处理交给pandas不要用UiPath逐行读单元格。这些都是血泪经验。有一个项目我最初用UiPath循环调用Python处理30个Excel文件耗时40分钟后来改成一次性传目录给Python批量处理耗时不到3分钟。差的这一个数量级就是设计取舍的价值。6.3 什么逻辑留在UiPath什么下沉Python我给自己定了一条简单的决策线需要操作界面、控制流程分支、发送通知的留在UiPath需要处理数据、跑算法、解析结构的全部下沉到Python。按照这个原则UiPath和Python的职责非常清楚留在UiPath下沉PythonUI操作、选择器、元素交互数据清洗、格式转换状态机、重试、异常分支pandas批量数据处理邮件通知、附件收发JSON/XML嵌套解析与业务系统稳的API对接加密签名、算法计算、模型推理这条线划得越清晰流程的维护成本越低。最忌讳的是这里用Python写一小段、那里用Python写一小段最后整个流程变成一团剪不断理还乱的线头。6.4 版本管理与日志规范Python脚本也是代码需要版本管理。如果脚本和.xaml文件一起放在项目目录里版本同步时脚本也会一起更新。Python脚本里最好用注释写上依赖包的版本# requirements: pandas2.0.0, openpyxl3.1.0Python侧的print输出可以在UiPath的活动输出日志里看到。我在Python函数里会习惯性地在关键节点打print这样一旦流程出问题UiPath的日志里直接能看到Python执行到了哪一步不用再单独开控制台调试。另外提一个习惯scripts目录下的每个Python文件开头写一段docstring说明这个文件是给哪个流程用的、有哪些函数、每个函数的出入参是什么。三个月后再回来维护你会感谢当时写下这些注释的自己。我在几个项目里反复打磨过这套调用方式最大的体感是把Python当成一个“计算引擎”而不是“脚本碎片”你的UiPath流程会清晰很多。最好用的调用姿势永远是让Python函数接收路径或JSON字符串、返回JSON字符串UiPath只负责编排和展示。最后送一个小建议不管你的Python脚本目前看起来多简单都请把入参和出参的格式写清楚尤其是返回的JSON结构。UiPath侧的同事不一定熟悉Python的数据结构这份注释能省掉你很多沟通成本。另外凡是涉及路径和编码的改动改完之后一定要把UiPath整个重启一遍再测否则你会以为自己改了没用白白浪费半小时查一个环境刷新问题。