uniapp实战：三步搞定文件下载、保存与预览（附完整代码）

Uniapp文件操作实战：从云端下载到本地预览的完整实现方案

在移动应用开发中，文件处理是一个看似基础却暗藏玄机的功能模块。无论是电商平台的商品详情PDF、教育应用的课件资料，还是企业内部系统的合同文档，文件下载、保存和预览都是用户高频使用的核心功能。很多Uniapp开发者初次接触这类需求时，往往会被平台差异、权限问题、文件路径处理等细节绊住脚步。

我最近在重构一个企业级应用时，就遇到了一个典型的场景：用户需要在手机端查看并签署电子合同。这个需求看似简单——点击按钮，下载文件，打开预览——但在实际开发中，却需要考虑H5与App的差异、文件存储位置、权限申请、用户体验优化等多个维度。经过几轮迭代和踩坑，我总结出了一套相对完善的实现方案，今天就来详细拆解其中的关键技术和实践细节。

1. 理解Uniapp文件操作的核心API与平台差异

1.1 三大核心API的功能定位

Uniapp为文件操作提供了三个核心API，它们各自承担着不同的职责，理解这一点是正确使用它们的前提。

uni.downloadFile - 这是整个流程的起点，负责将远程服务器上的文件下载到设备的临时存储区域。它的工作方式类似于浏览器中的下载行为，但有几个关键特点需要注意：

• 下载的文件会存储在临时目录中，这意味着文件可能被系统自动清理
• 成功回调中返回的是临时文件路径（tempFilePath），而不是最终保存路径
• 支持设置请求头（header），这对于需要身份验证的文件下载至关重要
• 可以监听下载进度，实现进度条等用户体验优化

// 基础下载示例
uni.downloadFile({
  url: 'https://example.com/files/contract.pdf',
  success: (res) => {
    if (res.statusCode === 200) {
      console.log('临时文件路径:', res.tempFilePath);
      // 这里获取的是临时路径，不是永久保存路径
    }
  },
  fail: (err) => {
    console.error('下载失败:', err);
  }
});

uni.saveFile - 这个API负责将临时文件保存到设备的永久存储中。这是很多开发者容易忽略的一步，如果不调用saveFile，下载的文件可能会在应用重启或系统清理时丢失。

注意：在H5环境中，uni.saveFile的行为与App端有所不同。H5端通常使用浏览器的下载机制，而App端则需要处理本地文件系统的写入操作。

uni.openDocument - 文件保存后的预览环节。这个API会根据文件类型调用系统默认的应用打开文件，比如PDF文件会用PDF阅读器打开，Word文档会用Office应用打开。

1.2 平台差异的深度解析

Uniapp的"一次开发，多端发布"优势在文件操作场景下需要特别小心处理。不同平台的实现机制和限制条件差异显著。

H5端的特殊性

在浏览器环境中，文件下载通常通过<a>标签的download属性或Blob对象实现。Uniapp在H5端对uni.downloadFile的实现就是基于这些Web API。但有几个重要限制：

1. 跨域问题：如果文件服务器没有配置CORS，下载会失败
2. 文件大小限制：大文件下载可能受浏览器内存限制
3. 保存路径不可控：用户通过浏览器下载对话框选择保存位置

<!-- H5端的条件编译实现 -->
<!-- #ifdef H5 -->
<a 
  href="https://example.com/files/document.pdf" 
  download="合同文件.pdf"
  class="download-btn"
>
  下载合同
</a>
<!-- #endif -->

App端的复杂性

在App端（包括iOS和Android），文件操作涉及更多底层权限和系统交互：

提示：在Android 10及以上版本，作用域存储（Scoped Storage）策略对文件访问有更严格的限制。如果应用需要访问公共目录，需要在manifest.json中声明权限，并在运行时动态申请。

条件编译的必要性

由于平台差异，在实际开发中几乎总是需要使用条件编译来区分处理逻辑：

// 统一的下载处理方法
async handleDownload() {
  // #ifdef APP-PLUS
  await this.downloadForApp();
  // #endif
  
  // #ifdef H5
  await this.downloadForH5();
  // #endif
}

2. 实战：构建健壮的文件下载与保存系统

2.1 基础实现与错误处理

一个完整的文件下载功能不能只考虑"成功路径"，还需要妥善处理各种异常情况。下面是一个增强版的实现示例：

/**
 * 文件下载与保存的完整流程
 * @param {string} fileUrl - 文件远程地址
 * @param {string} fileName - 建议的文件名
 */
async downloadAndSaveFile(fileUrl, fileName = '') {
  try {
    // 步骤1：显示加载状态
    uni.showLoading({
      title: '正在下载...',
      mask: true
    });
    
    // 步骤2：下载文件到临时目录
    const downloadResult = await new Promise((resolve, reject) => {
      uni.downloadFile({
        url: fileUrl,
        header: {
          'Authorization': `Bearer ${this.getToken()}` // 需要认证的文件
        },
        success: resolve,
        fail: reject
      });
    });
    
    if (downloadResult.statusCode !== 200) {
      throw new Error(`下载失败，状态码: ${downloadResult.statusCode}`);
    }
    
    // 步骤3：保存到本地永久存储
    const saveResult = await new Promise((resolve, reject) => {
      uni.saveFile({
        tempFilePath: downloadResult.tempFilePath,
        success: resolve,
        fail: reject
      });
    });
    
    // 步骤4：用户反馈
    uni.showToast({
      title: `文件已保存: ${this.getFileName(saveResult.savedFilePath)}`,
      icon: 'success',
      duration: 2000
    });
    
    return saveResult.savedFilePath;
    
  } catch (error) {
    console.error('文件操作失败:', error);
    
    // 根据错误类型提供不同的用户提示
    let errorMessage = '文件操作失败，请重试';
    if (error.errMsg && error.errMsg.includes('fail permission')) {
      errorMessage = '需要文件存储权限，请在设置中授权';
    } else if (error.errMsg && error.errMsg.includes('network')) {
      errorMessage = '网络连接失败，请检查网络设置';
    }
    
    uni.showModal({
      title: '操作失败',
      content: errorMessage,
      showCancel: false
    });
    
    return null;
  } finally {
    uni.hideLoading();
  }
}

2.2 权限处理的完整方案

在Android平台上，文件存储权限是必须处理的问题。以下是一个完整的权限处理模块：

// permissionManager.js - 权限管理模块
class PermissionManager {
  /**
   * 检查并申请存储权限
   * @returns {Promise<boolean>} 是否拥有权限
   */
  static async checkStoragePermission() {
    // #ifdef APP-PLUS
    if (plus.os.name === 'Android') {
      const androidVersion = parseInt(plus.os.version);
      
      // Android 6.0+ 需要动态权限申请
      if (androidVersion >= 6) {
        const permissions = [
          'android.permission.READ_EXTERNAL_STORAGE',
          'android.permission.WRITE_EXTERNAL_STORAGE'
        ];