# uni.uploadFile(options)

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

# 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="data.title"></page-head>
      <view class="uni-padding-wrap uni-common-mt">
        <view class="demo">
          <image v-if="data.imageSrc" :src="data.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 setup lang="uts">
  // #ifdef APP-ANDROID || APP-IOS || APP-HARMONY
  import {
    testInovkeUploadFile,
    CommonOptions
  } from '@/uni_modules/test-invoke-network-api'
  // #endif

  type DataType = {
    title: string;
    imageSrc: string;
    task: UploadTask | null;
    jest_result: boolean;
  }

  const data = reactive({
    title: 'uploadFile',
    imageSrc: '',
    task: null,
    //自动化测试例专用
    jest_result: false,
  } as DataType)

  onUnload(() => {
    data.imageSrc = '';
    uni.hideLoading();
    data.task?.abort();
  })

  const chooseImage = () => {
    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: '上传中'
        })
        data.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
            })
            data.imageSrc = imageSrc
          },
          fail: (err) => {
            console.log('uploadImage fail', err);
            uni.showModal({
              content: err.errMsg,
              showCancel: false
            });
          },
          complete: (res) => {
            uni.hideLoading();
            data.task = null
          }
        });
      },
      fail: (err) => {
        console.log('chooseImage fail', err)
      }
    })
  }

  //自动化测试例专用
  const jest_uploadFile = () => {
    const imageSrc = "/static/test-image/logo.png";
    uni.uploadFile({
      url: 'https://unidemo.dcloud.net.cn/upload', //仅为示例,非真实的接口地址
      filePath: imageSrc,
      name: 'file',
      formData: {
        'user': 'test'
      },
      success: () => {
        data.jest_result = true;
      },
      fail: () => {
        data.jest_result = false;
      },
    })
  }

  const 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: () => {
            data.jest_result = true;
          },
          fail: () => {
            data.jest_result = false;
          },
        })
      },
      fail: () => {
        data.jest_result = false
      }
    });
  }

  const jest_cookie_upload = (needCookie : boolean) => {
    const imageSrc = "/static/test-image/logo.png";
    uni.uploadFile({
      url: 'https://request.dcloud.net.cn/api/http/header/upload',
      filePath: imageSrc,
      name: 'file',
      success: (res : UploadFileSuccess) => {
        const responseData = JSON.parseObject(res.data)
        const errCode = responseData?.getNumber("errCode")
        if (errCode != null && errCode == 1000) {
          data.jest_result = needCookie ? false : true;
        } else {
          data.jest_result = needCookie ? true : false;
        }
      },
      fail: () => {
        data.jest_result = false;
      },
    })
  }

  const 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: () => {
        jest_cookie_upload(true)
      },
      fail: () => {
        data.jest_result = false;
      },
    });
  }

  const 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: () => {
        jest_cookie_upload(false)
      },
      fail: () => {
        data.jest_result = false;
      },
    });
  }

  const jest_files_upload = () => {
    const imageSrc = "/static/test-image/logo.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) {
          data.jest_result = true;
        }
      },
      fail: () => {
        data.jest_result = false;
      },
    })
  }

  const jest_uts_module_invoked = () => {
    // #ifdef APP-ANDROID || APP-IOS || APP-HARMONY
    testInovkeUploadFile({
      success: (res : any) => {
        data.jest_result = true
      },
      fail: (err : any) => {
        data.jest_result = false
      }
    } as CommonOptions)
    // #endif
  }

  const jest_uploadFileWithoutFile = () => {
    const imageSrc = "/static/test-image/logo.png";
    uni.uploadFile({
      url: 'https://unidemo.dcloud.net.cn/upload', //仅为示例,非真实的接口地址
      formData: {
        'user': 'test'
      },
      success: (res) => {
        console.log("success: ",res);
        data.jest_result = true;
      },
      fail: (err) => {
        console.log("fail: ", err);
        data.jest_result = false;
      },
    })
  }

  const 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 responseData = JSON.parseObject(res.data)
        const innerData = responseData?.getJSON("data")
        const header = innerData?.getJSON("requestHeaders")
        const uas = header?.getArray("user-agent")
        if(uas != null) {
          data.jest_result = (uas.length == 1)
        }
      },
      fail: () => {
        data.jest_result = false;
      },
    })
  }

  defineExpose({
    data,
    jest_uploadFile,
    jest_uploadFile_with_uni_env,
    jest_set_cookie,
    jest_delete_cookie,
    jest_files_upload,
    jest_uts_module_invoked,
    jest_uploadFileWithoutFile,
    jest_uploadFileVerifyUA
  })
</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等返回文件对象的接口的返回值作为要上传的文件