::: 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等返回文件对象的接口的返回值作为要上传的文件