---
name: "downloadFile"
mode: "kit"
versionRequirements:
  - { name: "BaseKit", version: "2.3.2" }
  - { name: "@ray-js/ray", version: "0.3.23" }
platform:
  - "iOS"
  - "Android"
async: true
title: "downloadFile - 下载文件资源到本地"
---

## downloadFile

> [VERSION] BaseKit >= 2.3.2 | @ray-js/ray >= 0.3.23

> [PLATFORM] iOS, Android

> ⚡ **支持 Promise 调用** — 不传 success / fail / complete 回调时，该方法返回 Promise。

### 描述

下载文件资源到本地。客户端直接发起一个 HTTPS GET 请求，返回文件的本地临时路径 (本地路径)，单次下载允许的最大文件为 200MB。使用前请注意阅读相关说明。 注意：请在服务端响应的 header 中指定合理的 Content-Type 字段，以保证客户端正确处理文件类型。

### 参数

| 属性 | 类型 | 必填 | 默认值 | 最低版本 | 描述 |
| --- | --- | --- | --- | --- | --- |
| `url` | `string` | 是 | - | `2.3.2` | 下载资源的 url |
| `header` | `Record<string, string>` | 否 | - | `2.3.2` | HTTP 请求的 Header，Header 中不能设置 Referer |
| `timeout` | `number` | 否 | - | `2.3.2` | 超时时间，单位为毫秒 |
| `filePath` | `string` | 否 | - | `2.3.2` | 指定文件下载后存储的路径 (本地路径) |
| `complete` | `() => void` | 否 | - | - | 接口调用结束的回调函数（调用成功、失败都会执行） |
| `success` | `(params: Object) => void` ↓见下方 | 否 | - | - | 接口调用成功的回调函数 |
| `fail` | `(params: Object) => void` ↓见下方 | 否 | - | - | 接口调用失败的回调函数 |

#### success 回调参数

| 属性 | 类型 | 最低版本 | 描述 |
| --- | --- | --- | --- |
| `tempFilePath` | `string` | `3.2.6` | 临时文件路径 (本地路径)。没传入 filePath 指定文件存储路径时会返回，下载后的文件会存储到一个临时文件 |
| `filePath` | `string` | `3.2.6` | 用户文件路径 (本地路径)。传入 filePath 时会返回，跟传入的 filePath 一致 |
| `statusCode` | `number` | `3.2.6` | 开发者服务器返回的 HTTP 状态码 |
| `profile` | `Profile` | `3.2.6` | 网络请求过程中一些调试信息 |

#### fail 回调参数

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `errorMsg` | `string` | 错误信息 |
| `errorCode` | `string \| number` | 错误码 |
| `innerError` | `Object` | 错误扩展 |

##### fail(params).innerError 的属性

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `errorCode` | `string \| number` | 错误扩展码 |
| `errorMsg` | `string` | 错误扩展信息 |


### 引用对象

##### `interface` Profile

| 属性 | 类型 | 最低版本 | 描述 |
| --- | --- | --- | --- |
| `redirectStart` | `number` | `3.2.6` | 第一个 HTTP 重定向发生时的时间。有跳转且是同域名内的重定向才算，否则值为 0 |
| `redirectEnd` | `number` | `3.2.6` | 最后一个 HTTP 重定向完成时的时间。有跳转且是同域名内部的重定向才算，否则值为 0 |
| `fetchStart` | `number` | `3.2.6` | 组件准备好使用 HTTP 请求抓取资源的时间，这发生在检查本地缓存之前 |
| `domainLookupStart` | `number` | `3.2.6` | DNS 域名查询开始的时间，如果使用了本地缓存（即无 DNS 查询）或持久连接，则与 fetchStart 值相等 |
| `domainLookupEnd` | `number` | `3.2.6` | DNS 域名查询完成的时间，如果使用了本地缓存（即无 DNS 查询）或持久连接，则与 fetchStart 值相等 |
| `connectStart` | `number` | `3.2.6` | HTTP（TCP） 开始建立连接的时间，如果是持久连接，则与 fetchStart 值相等。注意如果在传输层发生了错误且重新建立连接，则这里显示的是新建立的连接开始的时间 |
| `connectEnd` | `number` | `3.2.6` | HTTP（TCP） 完成建立连接的时间（完成握手），如果是持久连接，则与 fetchStart 值相等。注意如果在传输层发生了错误且重新建立连接，则这里显示的是新建立的连接完成的时间。注意这里握手结束，包括安全连接建立完成、SOCKS 授权通过 |
| `SSLconnectionStart` | `number` | `3.2.6` | SSL建立连接的时间,如果不是安全连接,则值为 0 |
| `SSLconnectionEnd` | `number` | `3.2.6` | SSL建立完成的时间,如果不是安全连接,则值为 0 |
| `requestStart` | `number` | `3.2.6` | HTTP请求读取真实文档开始的时间（完成建立连接），包括从本地读取缓存。连接错误重连时，这里显示的也是新建立连接的时间 |
| `requestEnd` | `number` | `3.2.6` | HTTP请求读取真实文档结束的时间 |
| `responseStart` | `number` | `3.2.6` | HTTP 开始接收响应的时间（获取到第一个字节），包括从本地读取缓存 |
| `responseEnd` | `number` | `3.2.6` | HTTP 响应全部接收完成的时间（获取到最后一个字节），包括从本地读取缓存 |
| `rtt` | `number` | `3.2.6` | 当次请求连接过程中实时 rtt |
| `estimate_nettype` | `string` | `3.2.6` | 评估的网络状态 slow 2g/2g/3g/4g |
| `httpRttEstimate` | `number` | `3.2.6` | 协议层根据多个请求评估当前网络的 rtt（仅供参考） |
| `transportRttEstimate` | `number` | `3.2.6` | 传输层根据多个请求评估的当前网络的 rtt（仅供参考） |
| `downstreamThroughputKbpsEstimate` | `number` | `3.2.6` | 评估当前网络下载的kbps |
| `throughputKbps` | `number` | `3.2.6` | 当前网络的实际下载kbps |
| `peerIP` | `string` | `3.2.6` | 当前请求的IP |
| `port` | `number` | `3.2.6` | 当前请求的端口 |
| `socketReused` | `boolean` | `3.2.6` | 是否复用连接 |
| `sendBytesCount` | `number` | `3.2.6` | 发送的字节数 |
| `receivedBytedCount` | `number` | `3.2.6` | 收到字节数 |


### 示例代码

#### Demo

```tsx
import { downloadFile } from '@ray-js/ray'

downloadFile({
  url: "https://airtake-public-data-1254153901.cos.ap-shanghai.myqcloud.com/ttttestfile/test_video.mp4",
  success: data => {
    console.log(data);
  },
  fail: error => {
    console.error(error);
  },
});
```