vue.js - Vue H5+ App 如何实现文件流下载到手机？

Question

使用vue开发的app,用的是hbuilderx创建h5+app项目来打包的，现在有一个附件下载功能，后端返回的文件流，前端怎样将文件下载到手机中

试过plus.io里面的方法，但没成功，希望有大佬提供处理方法

Answer 1

忘记之前从哪里借鉴的了，反正就是用了 5plus 的能力来下载。主要用到了 plus.downloader.createDownload 和 plus.io.convertLocalFileSystemURL 两个API。

因为上的比较急，没有考虑健壮性，单纯跑通了就这样用了。

import { ElMessage } from 'element-plus'

/**
 * 监听 5plus 的 ready 事件
 * @returns {Ref<boolean>} 5plus 是否 ready
 */
export const use5PlusReady = () => {
  const ready5Plus = ref(!!window?.plus)
  document.addEventListener("plusready", () => {
    ready5Plus.value = true
  }, false);
  return ready5Plus
}

/**
 * 使用 5Plus 能力下载文件
 * @param url 文件地址，需要是完整的文件地址
 * @param options 下载选项
 * @returns {Promise<string>} 文件地址
 */
export const downloadFileBy5Plus = (url: string, options?: PlusDownloaderDownloadOptions): Promise<string> => {
  return new Promise((resolve, reject) => {
    const dTask = plus.downloader.createDownload(url, options, (dFile, dStatus) => {
      if (dStatus === 200) {
        resolve(plus.io.convertLocalFileSystemURL(dFile.filename))
      } else {
        const errorMsg = dStatus === 404 ? 'File not found' : `Download file failed: ${dStatus}`
        ElMessage.error(errorMsg)
        reject({
          msg: errorMsg,
          status: dStatus,
          file: dFile,
          filePath: url
        })
      }
    })
    dTask.start()
  })
}

/**
 * 调用第三方程序打开指定的文件
 * @param fileUrl 文件地址
 * @param options 打开选项
 * @param errorCB 错误回调
 */
export const openFileBy3rdApp = (fileUrl: string, options?: PlusRuntimeOpenFileOptions, errorCB?: (error: string) => void) => {
  plus.runtime.openFile(fileUrl, options, errorCB)
}

/**
 * 调用第三方程序打开指定的URL
 * @param url 文件地址
 * @param errorCB 错误回调
 */
export const openWebUrlBy3rdApp = (url: string, errorCB?: (error: string) => void) => {
  plus.runtime.openURL(url, errorCB)
}

用的时候就是这样：

// 下载文件
const handleClickFileDownload = (item: FileItem) => {
  const ready5Plus = use5PlusReady()
  const fileUrl = `/file-sys/${item.bucketName}/${item.fileName}`
  if (ready5Plus.value) {
    const fileFullPath = (import.meta.env.VITE_BASE_URL + fileUrl).replace(/\/\//, '/')
    downloadFileBy5Plus(fileFullPath).then(openFileBy3rdApp)
  } else {
    downBlobFile(fileUrl, null, item.original)
  }
}

Answer 2

在 Vue H5+ App 中实现文件流下载到手机，可通过以下步骤操作（使用 plus.io 和 plus.downloader API）：

解决方案代码

import axios from 'axios';

// 文件下载方法
const downloadFile = async (fileUrl, fileName) => {
  try {
    // 1. 获取文件流 (responseType 必须是 'arraybuffer' 或 'blob')
    const response = await axios.get(fileUrl, {
      responseType: 'arraybuffer', // 关键：接收二进制数据
      headers: { /* 如有 token 等需添加 */ }
    });

    // 2. 将 ArrayBuffer 转为 Base64
    const base64Data = arrayBufferToBase64(response.data);
    
    // 3. 保存到手机本地
    plus.io.resolveLocalFileSystemURL('_doc/', (entry) => {
      entry.getFile(fileName, { create: true }, (fileEntry) => {
        fileEntry.createWriter((writer) => {
          writer.onwrite = () => {
            plus.nativeUI.toast(`下载成功：${fileName}`);
            console.log('文件路径：', fileEntry.toLocalURL());
          };
          writer.onerror = (e) => console.error('写入失败:', e.message);
          
          // 写入 Base64 数据
          writer.writeAsText(base64Data, 'base64');
        });
      });
    }, (e) => console.error('获取目录失败：', e.message));
    
  } catch (e) {
    console.error('下载失败:', e.message);
    plus.nativeUI.alert('下载失败，请重试');
  }
};

// ArrayBuffer 转 Base64 工具函数
const arrayBufferToBase64 = (buffer) => {
  const binary = [];
  const bytes = new Uint8Array(buffer);
  for (let i = 0; i < bytes.byteLength; i++) {
    binary.push(String.fromCharCode(bytes[i]));
  }
  return window.btoa(binary.join(''));
};

// 调用示例（在 Vue 方法中触发）
this.downloadFile('https://api.example.com/file', 'report.pdf');

关键说明

1. 数据流转 Base64
   后端返回的文件流需要转为 Base64 格式，因 plus.io 的 writeAsText 方法支持直接写入 Base64 数据。

2. 存储目录选择

   • _doc/: 应用私有目录（推荐，无需权限）
   • _downloads/: 系统下载目录（部分安卓需权限）
   • 使用 fileEntry.toLocalURL() 获取完整路径（如：file:///_doc/report.pdf）

3. 权限配置
   在 manifest.json 中添加以下权限：

   "permissions": {
     "Download": {}
   }

4. 大文件处理建议
   若文件超过 10MB：

   • 让后端提供直接下载 URL

   • 改用 plus.downloader（简单高效，支持断点续传）：

     const task = plus.downloader.createDownload(
     fileUrl, 
     { filename: '_doc/' + fileName },
     (d, status) => status === 200 ? console.log('成功') : console.log('失败')
     );
     task.start();

常见问题排查

1. 写入失败

   • 检查存储路径是否合法（避免中文/特殊字符）
   • 真机调试查看完整错误日志（HBuilderX -> 控制台）

2. 跨域问题
   确保后端配置 CORS 响应头：

   Access-Control-Allow-Origin: *
   Access-Control-Expose-Headers: Content-Disposition

3. 权限拒绝

   • iOS 需在 manifest.json 的 ios 节点添加：

     "UIFileSharingEnabled": true,
     "accesses": [ "Documents" ]

   • Android 9+ 需适配 FileSystem API

提示：优先考虑让后端提供直链文件 URL，使用 plus.downloader 是最稳定高效的方式，无需处理文件流转换。