::: sourceCode
## uni.uploadFile(options) @uploadfile
> issues: https://issues.dcloud.net.cn/?mid=api.network.uploadFile
> 源码: https://github.com/dcloudio/uni-app/tree/uni-app-x-alpha/src/uni_modules/uni-network
:::
将本地资源上传到开发者服务器。
### uploadFile 兼容性
Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61
推荐上传到uniCloud,uniCloud提供了更便宜CDN和更好的易用性,[详见](https://doc.dcloud.net.cn/uniCloud/ext-storage/intro.html)
### 参数
| 名称 | 类型 | 必填 |
| :- | :- | :- |
| options | **UploadFileOptions** | 是 |
#### options 的属性描述
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
| :- | :- | :- | :- | :-: | :- |
| url | string | 是 | | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | 开发者服务器 url |
| filePath | string | 否 | null | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | 要上传文件资源的路径, 支持uni.env |
| name | string | 否 | null | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | 文件对应的 key , 开发者在服务器端通过这个 key 可以获取到文件二进制内容 |
| files | Array<**UploadFileOptionFiles**> | 否 | null | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | 需要上传的文件列表。 |
| header | [UTSJSONObject](/uts/buildin-object-api/utsjsonobject.md) | 否 | null | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | HTTP 请求 Header, header 中不能设置 Referer |
| formData | [UTSJSONObject](/uts/buildin-object-api/utsjsonobject.md) | 否 | null | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | HTTP 请求中其他额外的 form data |
| timeout | number | 否 | 120000 | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | 超时时间,单位 ms |
| success | (result: [UploadFileSuccess](#uploadfilesuccess-values)) => void | 否 | null | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | 成功返回的回调函数 |
| fail | (result: [UploadFileFail](#uploadfilefail-values)) => void | 否 | null | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | 失败的回调函数 |
| complete | (result: any) => void | 否 | null | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | 结束的回调函数(调用成功、失败都会执行) |
##### files 的属性描述
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
| :- | :- | :- | :- | :-: | :- |
| name | string | 否 | "file" | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | multipart 提交时,表单的项目名,默认为 file,如果 name 不填或填的值相同,可能导致服务端读取文件时只能读取到一个文件。 |
| uri | string | 是 | | Web: x; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | 要上传文件资源的路径 |
| file | any | 否 | | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: x | 要上传的文件对象 |
#### UploadFileSuccess 的属性值 @uploadfilesuccess-values
| 名称 | 类型 | 必备 | 兼容性 | 描述 |
| :- | :- | :- | :-: | :- |
| data | string | 是 | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | 开发者服务器返回的数据 |
| statusCode | number | 是 | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | 开发者服务器返回的 HTTP 状态码 |
#### UploadFileFail 的属性值 @uploadfilefail-values
| 名称 | 类型 | 必备 | 描述 |
| :- | :- | :- | :- |
| errCode | number | 是 | 错误码 |
| errSubject | string | 是 | 统一错误主题(模块)名称 |
| data | any | 否 | 错误信息中包含的数据 |
| cause | [Error](/err-spec.md#unierror) | 否 | 源错误信息,可以包含多个错误,详见SourceError |
| errMsg | string | 是 | |
#### errCode 的属性描述
| 合法值 | 描述 |
| :- | :- |
| 5 | 接口超时 |
| 1000 | 服务端系统错误 |
| 100001 | json数据解析错误 |
| 100002 | 错误信息json解析失败 |
| 100003 | json解析类型转换失败 |
| 600003 | 网络中断 |
| 600008 | data参数类型不合法 |
| 600009 | URL格式不合法 |
| 600010 | Cronet模块加载失败 |
| 602001 | request系统错误 |
### 返回值
| 类型 |
| :- |
| [UploadTask](#uploadtask-values) |
#### UploadTask 的方法 @uploadtask-values
#### abort(): void, @abort
abort
中断上传任务。
##### abort 兼容性
Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61
#### onProgressUpdate(callback: UploadFileProgressUpdateCallback): void, @onprogressupdate
onProgressUpdate
监听上传进度变化。
##### onProgressUpdate 兼容性
Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61
##### 参数
| 名称 | 类型 | 必填 |
| :- | :- | :- |
| callback | (result: [OnProgressUpdateResult](#onprogressupdateresult-values)) => void | 是 |
##### OnProgressUpdateResult 的属性值 @onprogressupdateresult-values
| 名称 | 类型 | 必备 | 兼容性 | 描述 |
| :- | :- | :- | :-: | :- |
| progress | number | 是 | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | 上传进度百分比 |
| totalBytesSent | number | 是 | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | 已经上传的数据长度,单位 Bytes |
| totalBytesExpectedToSend | number | 是 | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | 预期需要上传的数据总长度,单位 Bytes |
::: danger 注意事项
- 在4.25版本iOS平台增加了Task原生对象自动销毁的逻辑,即上传完成后自动释放原生的Task对象,建议开发者在`complete`回调中置空Task对象,例
```typescript
complete: () => {
this.task = null
},
```
如不释放,在调用Task对象的方法将导致控制台报错:
`error: instance object does not exist: id:15`
:::
### 示例
示例为[hello uni-app x alpha分支](https://gitcode.com/dcloud/hello-uni-app-x/blob/prod_alpha/pages/API/upload-file/upload-file.uvue),与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例[另见](https://gitcode.com/dcloud/hello-uni-app-x/blob/master//pages/API/upload-file/upload-file.uvue)
::: preview https://hellouniappx.dcloud.net.cn/web/#/pages/API/upload-file/upload-file
> appRedirect https://hellouniappx.dcloud.net.cn/appredirect.html?path=pages/API/upload-file/upload-file
>示例
```vue
+ 选择图片
```
:::
## 通用类型
### GeneralCallbackResult @generalcallbackresult-values
| 名称 | 类型 | 必备 | 描述 |
| :- | :- | :- | :- |
| errMsg | string | 是 | 错误信息 |
**注意**
- web端上传文件时仅能使用downloadFile、chooseImage等返回文件对象的接口的返回值作为要上传的文件