微信小程序文件上传下载API实战指南

1. 小程序文件传输实战指南

在小程序开发中，文件上传与下载是最基础也最常用的功能之一。无论是用户头像上传、图片分享还是文档管理，都离不开这两个核心功能。作为开发者，我们需要掌握微信小程序提供的文件传输API，并了解其中的技术细节和实际应用中的各种"坑"。

2. 文件上传全解析

2.1 wx.uploadFile核心参数详解

wx.uploadFile是小程序提供的文件上传API，它实际上封装了一个HTTPS POST请求，使用multipart/form-data格式传输数据。这个API看似简单，但每个参数都值得深入研究：

javascript复制wx.uploadFile({
  url: 'https://your-server.com/upload',
  filePath: tempFilePaths[0],
  name: 'userFile',
  formData: {
    'userId': '12345'
  },
  success(res) {
    console.log('上传成功', res.data)
  }
})

关键参数解析：

• url：服务端接收地址，必须是HTTPS协议
• filePath：本地文件路径，通常来自wx.chooseImage等API的返回
• name：服务端用于识别文件的字段名，相当于HTML中<input type="file">的name属性
• formData：额外的表单数据，可以传递用户ID等元信息

特别注意：header中不能设置Referer字段，这是微信出于安全考虑的限制。如果需要身份验证，建议使用自定义header如Authorization。

2.2 上传进度监控与任务管理

UploadTask对象提供了丰富的控制能力，这在处理大文件上传时尤为重要：

javascript复制const uploadTask = wx.uploadFile({
  //...参数配置
})

// 监听上传进度
uploadTask.onProgressUpdate((res) => {
  console.log(`进度: ${res.progress}%`)
  console.log(`已上传: ${res.totalBytesSent}字节`)
  console.log(`总大小: ${res.totalBytesExpectedToSend}字节`)
})

// 需要时可以取消上传
setTimeout(() => {
  uploadTask.abort()
  console.log('上传已取消')
}, 5000)

实际开发中的经验：

1. 对于大文件上传，一定要实现进度显示，提升用户体验
2. 在网络不稳定的环境下，考虑实现断点续传功能
3. 上传超时时间建议根据文件大小动态设置，小文件可以短些(10s)，大文件需要更长(60s+)

2.3 服务端实现要点

一个完整的Spring Boot服务端实现示例：

java复制@RestController
public class FileController {
    private final String UPLOAD_DIR = "uploads/";

    @PostMapping("/upload")
    public String handleUpload(@RequestParam("userFile") MultipartFile file,
                             @RequestParam("userId") String userId) {
        if (file.isEmpty()) {
            return "文件不能为空";
        }

        try {
            // 创建日期目录
            String datePath = LocalDate.now().format(DateTimeFormatter.BASIC_ISO_DATE);
            Path dir = Paths.get(UPLOAD_DIR, datePath);
            Files.createDirectories(dir);

            // 生成唯一文件名
            String ext = FilenameUtils.getExtension(file.getOriginalFilename());
            String newName = UUID.randomUUID() + "." + ext;

            // 保存文件
            Path target = dir.resolve(newName);
            file.transferTo(target);

            return "/download/" + datePath + "/" + newName;
        } catch (IOException e) {
            e.printStackTrace();
            return "上传失败";
        }
    }
}

关键安全措施：

1. 文件类型检查：通过文件魔数(Magic Number)而非扩展名验证真实类型
2. 大小限制：在服务端也要做限制，防止大文件攻击
3. 病毒扫描：对上传文件进行安全扫描
4. 权限控制：确保用户只能访问自己有权限的文件

3. 文件下载深度剖析

3.1 wx.downloadFile使用技巧

文件下载API虽然简单，但使用时有许多需要注意的细节：

javascript复制wx.downloadFile({
  url: 'https://your-server.com/files/12