For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt, and this page is available as Markdown at /apps-plugin/docs/js-api/network/uploadFile.md.

uploadFile

上传本地文件,并返回可用于监听进度和中断上传的 UploadTask。

扫码预览

扫码预览 uploadFile

支持版本

前端库版本不低于 0.0.39。

支持平台

平台支持情况
Android支持
iOS支持
PC不支持
HarmonyOS不支持

支持场景

场景支持情况
页面支持
卡片不支持

接入准备

前置条件

  • url 需命中当前应用插件的上传域名白名单,filePath 需指向当前应用插件可访问的本地文件

使用说明

uploadFile 会同步返回可监听、可中断的 Promise 任务对象。 建议在调用后立即注册进度和响应头监听;不再需要上传时调用 UploadTask.abort。

  • 上传成功时 Promise resolve,上传失败或取消时 Promise reject;任务结束或不再使用时应移除监听,必要时调用 abort。

调用方式

异步 API

uploadFile(params: UploadFileParams): UploadTask

入参

名称类型必填默认值约束说明
enableProfilefalse否false-是否返回网络 profile。豆包当前仅支持 false。
filePathstring是--要上传文件资源的本地路径。
formDataRecord<string, unknown>否--额外的 form-data 字段。对象或数组值会按 JSON 字符串传递。
headerRecord<string, string>否--HTTP 请求 Header。`referer`、`user-agent`、`content-type` 等由豆包客户端管理的字段不会被业务覆盖。
namestring是--文件对应的 form field name/key,服务端通过该 key 获取文件内容;multipart filename 使用 filePath 的 basename。
timeoutnumber否--超时时间,单位 ms;不传时使用豆包客户端的默认超时配置。
urlstring是--开发者服务器地址,需为完整的 HTTP/HTTPS URL,并通过豆包配置的上传域名白名单校验。

调用示例

import { uploadFile } from '@doubao-dev/framework/api';

const task = uploadFile({
  url: 'https://example.com/upload',
  filePath: 'ttfile://temp/example.png',
  name: 'file',
  formData: { scene: 'profile' }
});

task
  .then((result) => {
    console.log(result.statusCode, result.data);
  })
  .catch((error) => {
    console.error(error);
  })
  .finally(() => {
    console.log('upload finished');
  });

task.onProgressUpdate((event) => {
  console.log(event.progress, event.totalBytesSent);
});
task.onHeadersReceived((event) => {
  console.log(event.header);
});

// 不再需要上传时中断任务。
// task.abort();

成功返回

名称类型必返说明
datastring否服务器返回的数据。
headerRecord<string, string>是HTTP 响应头。
statusCodenumber是HTTP 状态码。

返回示例

{
  "statusCode": 200,
  "header": {
    "content-type": "application/json"
  },
  "data": "{\"ok\":true}"
}

错误处理

错误对象和通用错误码见 通用错误处理。

失败示例

{
  "errMsg": "uploadFile:fail request time out",
  "errNo": 121920,
  "errorCode": 121920
}

错误码

errNoerrMsg平台触发条件处理建议
121999uploadFile:fail url is invalidAndroid、iOSurl 缺失或不是有效上传地址传入完整的 HTTP/HTTPS URL
121999uploadFile:fail name is requiredAndroid、iOSname 缺失或为空传入服务端接收文件所使用的 form field name
121901uploadFile:fail url not in domain listAndroid、iOSurl 未命中上传域名白名单在应用插件配置中添加上传域名后重试
121902uploadFile:fail no file existAndroid、iOSfilePath 为空、文件不存在或路径不是文件使用文件 API 获取当前应用插件可访问的有效文件路径
121905uploadFile:fail upload file abortAndroid、iOS调用 UploadTask.abort 中断上传按业务需要处理取消状态,无需自动重试
121906uploadFile:fail file path permission deniedAndroid、iOS当前应用插件无权访问 filePath改用当前应用插件目录内的文件
121920uploadFile:fail request time outAndroid、iOS上传超过豆包客户端的超时时间检查网络或设置合理的 timeout 后重试
121985uploadFile:fail network unavailableAndroid、iOS当前网络不可用恢复网络连接后重试
121991uploadFile:fail network errorAndroid、iOS上传过程中发生网络错误检查网络和服务端状态后重试
121992uploadFile:fail enableProfile is not supportedAndroid、iOSenableProfile 设置为 true移除 enableProfile 或设置为 false