上传文件

上传文件 用于在浏览器 RPA 中从对象存储拉取文件，并上传到类型为 file 的输入框（或支持拖放上传的区域），支持智能上传策略与多文件批量上传，常用于文档、图片等上传的自动化场景。

指令标识：UploadFileFromS3
指令类型：网页指令
指令描述：从对象存储拉取文件并上传到类型为 file 的输入框中，支持多种上传策略

先选使用方式

工作流支持「可视化编排」和「代码编排」两种创建方式。上传文件 在两种方式里都能用，核心业务参数一致，区别主要是你通过界面配置，还是通过 Python 脚本配置。

方式	怎么用	适合人群
可视化编排（推荐先学）	拖入「上传文件」节点，在右侧表单选择上传控件并填写文件存储路径	大多数用户，零代码，适合快速搭建和调试
代码编排（Python）	在脚本中调用 bots.uploadFileFromS3(selector="...", s3Paths="...")	熟悉代码、需要复用脚本或批量生成流程的用户

第一次使用建议先用可视化编排跑通，再迁移到 Python 代码编排。下方「参数说明」同时给出界面字段和代码参数名，方便两种方式对应。

什么时候用？

• 在网页表单中模拟用户上传文件。
• 一次性批量上传多个文件到支持多选的上传控件。
• 在自动化测试中验证文件上传功能。

上传完成后，常接 验证元素存在 或 延迟 确认上传结果。

使用前确认

• 文件已存放在对象存储，并拿到完整、可下载的访问路径。
• 上传控件可定位，通常指向 input[type='file'] 元素。
• 多文件上传时，目标控件支持多选，路径用英文逗号分隔。
• 该指令属于元素定位类，默认失败即中止（报错中止）：找不到上传控件会抛出异常。
• 上传超时通过「文件上传配置」inputFilesOptions 设置；元素定位超时通过「查找元素高级配置」findElementOptions 设置。
• 若上传控件在 iframe 中，需填写 iframe 页面定位器。

可视化编排：从 0 到跑通

下面用一个常见场景演示：在文件上传页面上传一张图片。按 4 步即可跑起来：

1. 在前序流程中通过 打开网页 打开上传页面。
2. 添加 上传文件 节点，在 文件选择元素选择器 中选择或填写上传控件：

//input[@type='file']

3. 在 文件S3路径 填写完整的文件存储路径，例如 https://example.com/assets/files/test-file.png。
4. 点击运行，确认文件已上传到目标控件，再接验证或后续提交。

参数说明

输入参数

界面名称	代码属性名	类型	必填	默认值	说明
文件选择元素选择器	selector	String	是	-	用于选择上传控件的元素选择器，不能为空，通常指向 input[type='file']，支持从元素库选择或手动填写 XPath 等定位器
文件S3路径	s3Paths	String	是	-	待上传文件的存储路径，支持多个文件用英文逗号分隔，不能为空
文件上传配置	inputFilesOptions	JSON	否	-	高级选项。文件上传的高级配置，包含上传方式、上传超时（timeout，单位毫秒）等，例如 {"timeout":30000}
iframe页面定位器	frameSelector	String	否	-	高级选项。iframe 的 XPath，目标元素在 iframe 中时填写，例如 //html/iframe
查找元素高级配置	findElementOptions	JSON	否	-	高级选项。元素查找配置，可设置元素定位超时，例如 {"timeout":5000}，单位毫秒

输出参数

无。

成功标准

• 运行成功，文件被上传到目标控件。
• 上传控件显示已选择对应文件（或文件名），后续提交可正常进行。
• 运行日志中没有下载失败、找不到元素或上传超时错误。

运行后你会看到（以上面场景为例）：

• 上传控件显示已选择 test-file.png，可继续提交表单完成上传。

失败排查

现象 / 报错原文	可能原因	处理建议
找不到上传控件	选择器有误或元素未加载	核对选择器，在 findElementOptions 中增大 timeout
文件下载失败	文件路径错误或不可访问	确认 s3Paths 为完整、可下载的路径
上传超时	文件较大或网络较慢	在 inputFilesOptions 的 timeout 中增大上传超时
多文件只上传了部分	控件不支持多选或分隔符不对	确认控件支持多选，多个路径用英文逗号分隔
iframe 内控件找不到	未填写 iframe 定位器	在「iframe页面定位器」填写对应 XPath

Python 代码编排

代码编排以 Python 为主。运行上下文由代码编排模板创建，示例里只需要关注业务指令本身。

# 先打开上传页面
bots.openUrl(url="https://example.com/upload")
# 上传文件到目标控件
bots.uploadFileFromS3(
    selector="//input[@type='file']",
    s3Paths="https://example.com/assets/files/test-file.png",
)

如需自定义上传超时和元素定位超时：

bots.uploadFileFromS3(
    selector="//input[@type='file']",
    s3Paths="https://example.com/assets/files/test-file.png",
    inputFilesOptions='{"timeout":30000}',
    findElementOptions='{"timeout":5000}',
)

可视化表单里的「文件选择元素选择器」「文件S3路径」「文件上传配置」「查找元素高级配置」分别对应代码里的 selector、s3Paths、inputFilesOptions、findElementOptions。

如果你想在工作流中通过节点动态编排指令，可使用 执行指令（XML）节点。

常见问题

Q1：文件路径必须是什么格式？

A： 必须是完整的 URL，含协议和完整路径，例如 https://example.com/assets/files/file.png，且具有下载权限。

Q2：如何上传多个文件？

A： 用英文逗号分隔多个路径，例如 https://example.com/assets/a.jpg,https://example.com/assets/b.pdf，并确保控件支持多选。

Q3：上传超时应设置多长？

A： 根据文件大小调整：小文件（约 10MB）可设 30 秒，大文件（约 100MB）建议 5 分钟或更长，批量上传应增大超时。

Q4：上传控件在 iframe 中怎么办？

A： 使用「iframe页面定位器」指定 iframe 的 XPath，例如 //iframe[@id='upload-frame']。

相关指令

• 点击元素（推荐）
• 验证元素存在
• 延迟