微信小程序下载视频时无法保存到相册

Question

在微信小程序中，调用 `wx.downloadFile` 下载视频后，通过 `wx.saveVideoToPhotosAlbum` 保存到相册时，常出现“保存失败”或接口回调 success 却未实际写入相册的问题。该问题多发于 iOS 系统，主因是临时文件路径（tempFilePath）格式不兼容或文件损坏。部分安卓机型则因权限限制需手动授权存储权限。此外，微信基础库版本差异也导致兼容性问题，低版本可能无法正确触发保存流程。开发者易忽略对 `downloadFile` 返回的 header 类型校验，若服务端返回 Content-Type 不为视频格式，亦会导致下载文件无效，最终保存失败。

Answer 1

微信小程序视频下载与相册保存的深度解析与实践

1. 问题背景与现象描述

在微信小程序开发中，调用 wx.downloadFile 下载视频后，使用 wx.saveVideoToPhotosAlbum 将其保存至用户设备相册，是常见的功能需求。然而，大量开发者反馈存在“保存失败”或回调 success 但实际未写入相册的问题。

• iOS 系统上尤为常见，表现为临时路径格式不兼容或文件损坏。
• Android 设备则多因存储权限未授权导致静默失败。
• 部分低版本微信客户端（基础库低于 2.10.0）存在 API 兼容性缺陷。
• 服务端返回错误的 Content-Type（如 application/octet-stream），导致文件无法识别为有效视频。

2. 根本原因分析

平台	主要问题	技术根源
iOS	tempFilePath 路径格式异常	路径含 file:// 前缀或非沙盒路径
Android	保存无响应	未动态申请 WRITE_EXTERNAL_STORAGE 权限
All	success 回调但无文件	文件损坏或非 MP4/H.264 编码
All	接口调用无效	基础库版本 < 2.8.0 不支持 saveVideoToPhotosAlbum
All	下载内容非视频	服务端返回 Content-Type 错误

3. 关键排查流程图

graph TD
    A[开始下载视频] --> B{wx.downloadFile}
    B -- success --> C{检查 header['Content-Type']}
    C -- video/* --> D[获取 tempFilePath]
    C -- 非视频类型 --> Z[提示: 文件类型不支持]
    D --> E{平台判断}
    E -- iOS --> F[去除 file:// 前缀]
    E -- Android --> G[请求存储权限]
    G -- 授权成功 --> H[调用 wx.saveVideoToPhotosAlbum]
    G -- 拒绝 --> I[引导用户手动开启权限]
    F --> H
    H -- success --> J[提示: 保存成功]
    H -- fail --> K[记录错误日志并降级处理]
    

4. 解决方案与最佳实践

1. 校验下载响应头： 在 wx.downloadFile 成功回调中，必须检查 header['Content-Type'] 是否以 video/ 开头。
2. 路径规范化（iOS）： 对 tempFilePath 进行字符串处理，移除 file:// 前缀，避免路径解析错误。
3. 权限适配（Android）： 使用 wx.getSetting 检查 scope.writePhotosAlbum，若未授权则调用 wx.authorize 请求。
4. 基础库版本兜底： 判断 wx.canIUse('saveVideoToPhotosAlbum')，否则提示升级微信或跳转说明页。
5. 文件完整性验证： 可通过 wx.getFileInfo 获取 size 和 digest，确保文件非空且完整。
6. 编码兼容性： 服务端应确保输出标准 MP4 容器，H.264 视频编码 + AAC 音频编码，提升跨平台兼容性。
7. 用户引导策略： 保存失败时提供明确提示，并附带“如何开启相册权限”的图文指引。
8. 异常监控上报： 记录失败 case 的设备型号、系统版本、微信版本、错误码，用于后续优化。
9. 测试覆盖建议： 必须覆盖 iOS 14+/15+、Android 10/11/12/13 多机型真机测试。
10. 降级方案设计： 当保存失败时，可提供“长按视频保存”或“分享到朋友圈自动保存”作为替代路径。

5. 核心代码实现示例

// 下载并保存视频主逻辑
function downloadAndSaveVideo(videoUrl) {
  // 检查 API 可用性
  if (!wx.canIUse('saveVideoToPhotosAlbum')) {
    wx.showToast({ title: '微信版本过低', icon: 'none' });
    return;
  }

  wx.downloadFile({
    url: videoUrl,
    success: (res) => {
      if (res.statusCode !== 200) {
        wx.showToast({ title: '下载失败', icon: 'none' });
        return;
      }

      const contentType = res.header?.['Content-Type'] || '';
      if (!contentType.startsWith('video/')) {
        wx.showToast({ title: '文件类型不支持', icon: 'none' });
        return;
      }

      let tempPath = res.tempFilePath;

      // iOS 路径兼容处理
      if (tempPath.startsWith('file://')) {
        tempPath = tempPath.replace('file://', '');
      }

      // Android 存储权限检查
      wx.getSetting({
        success: (settingRes) => {
          if (!settingRes.authSetting['scope.writePhotosAlbum']) {
            wx.authorize({
              scope: 'scope.writePhotosAlbum',
              success: () => saveVideo(tempPath),
              fail: () => showPermissionGuide()
            });
          } else {
            saveVideo(tempPath);
          }
        }
      });
    },
    fail: () => wx.showToast({ title: '下载失败', icon: 'none' })
  });
}

function saveVideo(path) {
  wx.saveVideoToPhotosAlbum({
    filePath: path,
    success: () => wx.showToast({ title: '已保存到相册' }),
    fail: (err) => {
      console.error('保存失败:', err);
      wx.showToast({ title: '保存失败，请重试', icon: 'none' });
    }
  });
}