uni-app
uni-app x
uniCloud
HBuilder
uni 小程序 sdk
uni-app x
uni-app
uni-app x
uniCloud
HBuilder
uni 小程序 sdk
简体中文
API
uni.uploadFile(options)
uploadFile 兼容性
参数
UploadFileSuccess 的属性值
UploadFileFail 的属性值
返回值
UploadTask 的方法
abort(): void,
onProgressUpdate(callback: UploadFileProgressUpdateCallback): void,
示例
展示全部

# uni.uploadFile(options) GitCodeGitHub

将本地资源上传到开发者服务器。

# uploadFile 兼容性

Web 微信小程序 Android iOS iOS uni-app x UTS 插件 HarmonyOS
4.0 4.41 3.91 4.11 4.11 4.61

推荐上传到uniCloud，uniCloud提供了更便宜CDN和更好的易用性，详见

# 参数

名称 类型 必填 默认值 兼容性 描述
options UploadFileOptions 是 -
-
名称 类型 必备 默认值 兼容性 描述
url string 是 -
开发者服务器 url
filePath string 否 null
要上传文件资源的路径, 支持uni.env
name string 否 null
文件对应的 key , 开发者在服务器端通过这个 key 可以获取到文件二进制内容
files Array<UploadFileOptionFiles> 否 null
需要上传的文件列表。
名称 类型 必备 默认值 兼容性 描述
name string 否 "file"
multipart 提交时，表单的项目名，默认为 file，如果 name 不填或填的值相同，可能导致服务端读取文件时只能读取到一个文件。
uri string 是 -
要上传文件资源的路径
file any 否 -
要上传的文件对象
header UTSJSONObject 否 null
HTTP 请求 Header, header 中不能设置 Referer
formData UTSJSONObject 否 null
HTTP 请求中其他额外的 form data
timeout number 否 120000
超时时间，单位 ms
success (result: UploadFileSuccess) => void 否 null
成功返回的回调函数
fail (result: UploadFileFail) => void 否 null
失败的回调函数
complete (result: any) => void 否 null
结束的回调函数（调用成功、失败都会执行）
enableHttp2 boolean 否 -
需要基础库： 2.10.4

是否开启 http2
enableProfile boolean 否 -
是否开启 profile，默认开启。开启后可在接口回调的 res.profile 中查看性能调试信息。目前仅 iOS 端支持。
enableQuic boolean 否 -
需要基础库： 2.10.4

是否开启 Quic/h3 协议（iOS 微信目前使用 gQUIC-Q43；Android 微信在 v8.0.54 前使用 gQUIC-Q43，v8.0.54 开始使用 IETF QUIC，即 h3 协议；PC微信使用 IETF QUIC，即 h3 协议）
useHighPerformanceMode boolean 否 -
需要基础库： 3.4.1

使用高性能模式，暂仅支持 Android，默认关闭。该模式下有更优的网络性能表现。

# UploadFileSuccess 的属性值

名称 类型 必备 默认值 兼容性 描述
data string 是 -
开发者服务器返回的数据
statusCode number 是 -
开发者服务器返回的 HTTP 状态码

# UploadFileFail 的属性值

名称 类型 必备 默认值 兼容性 描述
errCode number 是 -
-
错误码
合法值 兼容性 描述
5
-
接口超时
1000
-
服务端系统错误
100001
-
json数据解析错误
100002
-
错误信息json解析失败
100003
-
json解析类型转换失败
600003
-
网络中断
600008
-
data参数类型不合法
600009
-
URL格式不合法
602001
-
request系统错误
errSubject string 是 -
-
统一错误主题（模块）名称
data any 否 -
-
错误信息中包含的数据
cause Error 否 -
-
源错误信息，可以包含多个错误，详见SourceError
errMsg string 是 -
-

# 返回值

类型
UploadTask

# UploadTask 的方法

# abort(): void,

abort 中断上传任务。

# abort 兼容性
Web 微信小程序 Android iOS iOS uni-app x UTS 插件 HarmonyOS
4.0 4.41 3.91 4.11 4.11 4.61

# onProgressUpdate(callback: UploadFileProgressUpdateCallback): void,

onProgressUpdate 监听上传进度变化。

# onProgressUpdate 兼容性
Web 微信小程序 Android iOS iOS uni-app x UTS 插件 HarmonyOS
4.0 4.41 3.91 4.11 4.11 4.61
# 参数
名称 类型 必填 默认值 兼容性 描述
callback (result: OnProgressUpdateResult) => void 是 -
-
# OnProgressUpdateResult 的属性值
名称 类型 必备 默认值 兼容性 描述
progress number 是 -
上传进度百分比
totalBytesSent number 是 -
已经上传的数据长度，单位 Bytes
totalBytesExpectedToSend number 是 -
预期需要上传的数据总长度，单位 Bytes

注意事项

  • 在4.25版本iOS平台增加了Task原生对象自动销毁的逻辑，即上传完成后自动释放原生的Task对象，建议开发者在complete回调中置空Task对象，例
complete: () => {
            this.task = null
          },

如不释放，在调用Task对象的方法将导致控制台报错： error: instance object does not exist: id:15

# 示例

示例为hello uni-app x alpha分支，与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见

扫码体验（手机浏览器跳转到App直达页）

示例

<template>
  <!-- #ifdef APP -->
  <scroll-view class="page-scroll-view">
  <!-- #endif -->
    <view>
      <page-head :title="title"></page-head>
      <view class="uni-padding-wrap uni-common-mt">
        <view class="demo">
          <image v-if="imageSrc" :src="imageSrc" class="image" mode="widthFix"></image>
          <text v-else class="uni-hello-addfile" @click="chooseImage">+ 选择图片</text>
        </view>
      </view>
    </view>
  <!-- #ifdef APP -->
  </scroll-view>
  <!-- #endif -->
</template>
<script>
  // #ifdef APP-ANDROID || APP-IOS || APP-HARMONY
  import {
    testInovkeUploadFile,
    CommonOptions
  } from '@/uni_modules/test-invoke-network-api'
  // #endif

  export default {
    data() {
      return {
        title: 'uploadFile',
        imageSrc: '',
        task: null as UploadTask | null,
        //自动化测试例专用
        jest_result: false,
      }
    },
    onLoad() {
    },
    onUnload() {
      this.imageSrc = '';
      uni.hideLoading();
      this.task?.abort();
    },
    methods: {
      chooseImage: function () {
        uni.chooseImage({
          count: 1,
          sizeType: ['compressed'],
          sourceType: ['album'],
          success: (res) => {
            console.log('chooseImage success, temp path is', res.tempFilePaths[0])
            var imageSrc = res.tempFilePaths[0]
            uni.showLoading({
              title: '上传中'
            })
            this.task = uni.uploadFile({
              url: 'https://unidemo.dcloud.net.cn/upload', //仅为示例，非真实的接口地址
              filePath: imageSrc,
              name: 'file',
              formData: {
                'user': 'test'
              },
              success: (res) => {
                console.log('uploadImage success, res is:', res)
                uni.showToast({
                  title: '上传成功',
                  icon: 'success',
                  duration: 1000
                })
                this.imageSrc = imageSrc
              },
              fail: (err) => {
                console.log('uploadImage fail', err);
                uni.showModal({
                  content: err.errMsg,
                  showCancel: false
                });
              },
              complete: (res) => {
                uni.hideLoading();
                this.task = null
              }
            });
          },
          fail: (err) => {
            console.log('chooseImage fail', err)
          }
        })
      },
      //自动化测试例专用
      jest_uploadFile() {
        const imageSrc = "/static/uni.png";
        uni.uploadFile({
          url: 'https://unidemo.dcloud.net.cn/upload', //仅为示例，非真实的接口地址
          filePath: imageSrc,
          name: 'file',
          formData: {
            'user': 'test'
          },
          success: () => {
            this.jest_result = true;
          },
          fail: () => {
            this.jest_result = false;
          },
        })
      },
      jest_uploadFile_with_uni_env() {
        /**
         * 微信小程序只支持USER_DATA_PATH，且子目录未创建的情况下不能直接下载到子目录内
         */
        const filePath = `${uni.env.USER_DATA_PATH}/uni-app.png`
        uni.downloadFile({
          url: "https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/uni-app.png",
          filePath: filePath,
          success: () => {
            uni.uploadFile({
              url: 'https://unidemo.dcloud.net.cn/upload', //仅为示例，非真实的接口地址
              filePath: filePath,
              name: 'file',
              success: () => {
                this.jest_result = true;
              },
              fail: () => {
                this.jest_result = false;
              },
            })
          },
          fail: () => {
            this.jest_result = false
          }
        });
      },
      jest_set_cookie() {
        uni.request({
          url: "https://request.dcloud.net.cn/api/http/header/setCookie",
          method: "GET",
          timeout: 6000,
          sslVerify: false,
          withCredentials: false,
          firstIpv4: false,
          success: () => {
            this.jest_cookie_upload(true)
          },
          fail: () => {
            this.jest_result = false;
          },
        });
      },

      jest_delete_cookie() {
        uni.request({
          url: "https://request.dcloud.net.cn/api/http/header/deleteCookie",
          method: "GET",
          timeout: 6000,
          sslVerify: false,
          withCredentials: false,
          firstIpv4: false,
          success: () => {
            this.jest_cookie_upload(false)
          },
          fail: () => {
            this.jest_result = false;
          },
        });
      },
      jest_cookie_upload(needCookie : boolean) {
        const imageSrc = "/static/uni.png";
        uni.uploadFile({
          url: 'https://request.dcloud.net.cn/api/http/header/upload',
          filePath: imageSrc,
          name: 'file',
          success: (res : UploadFileSuccess) => {
            const data = JSON.parseObject(res.data)
            const errCode = data?.getNumber("errCode")
            if (errCode != null && errCode == 1000) {
              this.jest_result = needCookie ? false : true;
            } else {
              this.jest_result = needCookie ? true : false;
            }
          },
          fail: () => {
            this.jest_result = false;
          },
        })
      },
      jest_files_upload() {
        const imageSrc = "/static/uni.png";
        uni.uploadFile({
          url: 'https://unidemo.dcloud.net.cn/upload',
          files: [
            {
              name: "file1",
              uri: imageSrc
            } as UploadFileOptionFiles,
            {
              name: "file2",
              uri: imageSrc
            } as UploadFileOptionFiles
          ],
          success: (res : UploadFileSuccess) => {
            if (res.statusCode == 200) {
              this.jest_result = true;
            }
          },
          fail: () => {
            this.jest_result = false;
          },
        })
      },
      jest_uts_module_invoked() {
        // #ifdef APP-ANDROID || APP-IOS || APP-HARMONY
        testInovkeUploadFile({
          success: (res : any) => {
            this.jest_result = true
          },
          fail: (err : any) => {
            this.jest_result = false
          }
        } as CommonOptions)
        // #endif
      },
      jest_uploadFileWithoutFile(){
        const imageSrc = "/static/uni.png";
        uni.uploadFile({
          url: 'https://unidemo.dcloud.net.cn/upload', //仅为示例，非真实的接口地址
          formData: {
            'user': 'test'
          },
          success: (res) => {
            console.log("success: ",res);
            this.jest_result = true;
          },
          fail: (err) => {
            console.log("fail: ", err);
            this.jest_result = false;
          },
        })
      },
      jest_uploadFileVerifyUA(){
        uni.uploadFile({
          url: 'https://request.dcloud.net.cn/api/http/header/upload',
          header:{
            "User-Agent":"custom"
          },
          formData: {
            'user': 'test'
          },
          success: (res : UploadFileSuccess) => {
            const data = JSON.parseObject(res.data)
            const innerData = data?.getJSON("data")
            const header = innerData?.getJSON("requestHeaders")
            const uas = header?.getArray("user-agent")
            if(uas != null) {
              this.jest_result = (uas.length == 1)
            }
          },
          fail: () => {
            this.jest_result = false;
          },
        })
      }
    }
  }
</script>

<style>
  .image {
    width: 100%;
  }

  .demo {
    background: #fff;
    padding: 25px;
    justify-content: center;
    align-items: center;
  }

  .uni-hello-addfile {
    text-align: center;
    background: #fff;
    padding: 25px;
    margin-top: 10px;
    font-size: 19px;
    color: #808080;
  }
</style>

# 参见

# 通用类型

# GeneralCallbackResult

名称 类型 必备 默认值 兼容性 描述
errMsg string 是 -
错误信息

注意

  • web端上传文件时仅能使用downloadFile、chooseImage等返回文件对象的接口的返回值作为要上传的文件
本页导读
uni.uploadFile(options)
uploadFile 兼容性
参数
UploadFileSuccess 的属性值
UploadFileFail 的属性值
返回值
UploadTask 的方法
abort(): void,
onProgressUpdate(callback: UploadFileProgressUpdateCallback): void,
示例
参见
通用类型
GeneralCallbackResult