> 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.

# uploadFile

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

## 扫码预览

![扫码预览 uploadFile](https://api.qrserver.com/v1/create-qr-code/?size=200x200\&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fnetwork%252Fupload-file%252Findex)

## 支持版本

前端库版本不低于 `0.0.39`。

## 支持平台

<table>
<thead>
<tr><th>平台</th><th>支持情况</th></tr>
</thead>
<tbody>
<tr><td>Android</td><td>支持</td></tr>
<tr><td>iOS</td><td>支持</td></tr>
<tr><td>PC</td><td>不支持</td></tr>
<tr><td>HarmonyOS</td><td>不支持</td></tr>
</tbody>
</table>

## 支持场景

<table>
<thead>
<tr><th>场景</th><th>支持情况</th></tr>
</thead>
<tbody>
<tr><td>页面</td><td>支持</td></tr>
<tr><td>卡片</td><td>不支持</td></tr>
</tbody>
</table>

## 接入准备

### 前置条件

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

## 使用说明

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

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

## 调用方式

### 异步 API

```typescript
uploadFile(params: UploadFileParams): UploadTask
```

## 入参

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

## 调用示例

```typescript
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();
```

## 成功返回

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>data</code></td><td><code>string</code></td><td>否</td><td>服务器返回的数据。</td></tr>
<tr><td><code>header</code></td><td><code>Record&lt;string, string&gt;</code></td><td>是</td><td>HTTP 响应头。</td></tr>
<tr><td><code>statusCode</code></td><td><code>number</code></td><td>是</td><td>HTTP 状态码。</td></tr>
</tbody>
</table>

### 返回示例

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

## 错误处理

错误对象和通用错误码见 [通用错误处理](/apps-plugin/docs/js-api/common-errors.md#错误返回)。

### 失败示例

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

### 错误码

<table>
<thead>
<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
</thead>
<tbody>
<tr><td><code>121999</code></td><td><code>uploadFile:fail url is invalid</code></td><td>Android、iOS</td><td>url 缺失或不是有效上传地址</td><td>传入完整的 HTTP/HTTPS URL</td></tr>
<tr><td><code>121999</code></td><td><code>uploadFile:fail name is required</code></td><td>Android、iOS</td><td>name 缺失或为空</td><td>传入服务端接收文件所使用的 form field name</td></tr>
<tr><td><code>121901</code></td><td><code>uploadFile:fail url not in domain list</code></td><td>Android、iOS</td><td>url 未命中上传域名白名单</td><td>在应用插件配置中添加上传域名后重试</td></tr>
<tr><td><code>121902</code></td><td><code>uploadFile:fail no file exist</code></td><td>Android、iOS</td><td>filePath 为空、文件不存在或路径不是文件</td><td>使用文件 API 获取当前应用插件可访问的有效文件路径</td></tr>
<tr><td><code>121905</code></td><td><code>uploadFile:fail upload file abort</code></td><td>Android、iOS</td><td>调用 UploadTask.abort 中断上传</td><td>按业务需要处理取消状态，无需自动重试</td></tr>
<tr><td><code>121906</code></td><td><code>uploadFile:fail file path permission denied</code></td><td>Android、iOS</td><td>当前应用插件无权访问 filePath</td><td>改用当前应用插件目录内的文件</td></tr>
<tr><td><code>121920</code></td><td><code>uploadFile:fail request time out</code></td><td>Android、iOS</td><td>上传超过豆包客户端的超时时间</td><td>检查网络或设置合理的 timeout 后重试</td></tr>
<tr><td><code>121985</code></td><td><code>uploadFile:fail network unavailable</code></td><td>Android、iOS</td><td>当前网络不可用</td><td>恢复网络连接后重试</td></tr>
<tr><td><code>121991</code></td><td><code>uploadFile:fail network error</code></td><td>Android、iOS</td><td>上传过程中发生网络错误</td><td>检查网络和服务端状态后重试</td></tr>
<tr><td><code>121992</code></td><td><code>uploadFile:fail enableProfile is not supported</code></td><td>Android、iOS</td><td>enableProfile 设置为 true</td><td>移除 enableProfile 或设置为 false</td></tr>
</tbody>
</table>
