微信小程序直传阿里云 OSS 实践指南（V4 签名 · 秒传支持 · 高性能封装）

---

前言

本文是我在实际项目中实现微信小程序直传阿里云 OSS 的完整方案总结，涵盖从权限配置到上传逻辑封装，再到上传优化与秒传处理，意在快速构建高性能、可维护的文件上传能力，也帮助后来者少走弯路。

---

一、为什么要使用直传 OSS？

传统小程序上传图片/视频的方式，往往是：

小程序 ➝ 后端中转 ➝ 阿里云 OSS

这种方式存在三大问题：

•	上传慢：服务端中转造成延迟
•	成本高：中转占带宽、占存储
•	不稳定：服务端并发压力大时更容易失败

直传方案优势明显：

优势	说明
较低宽带成本	文件直接由用户上传至OSS，无需服务端中转
提升上传速度	小程序原生uploadfile支持高效直传
提升安全性	使用STS临时授权，避免泄露秘钥
灵活扩展	可支持秒传、预签名、CDN访问等优化法案

二、整体架构与实现思路

用户选择文件
    ↓
调用后端签名接口获取 OSS V4 签名凭证
    ↓
使用 wx.uploadFile 将文件直传到 OSS
    ↓
上传成功后提交文件元信息给后端（如 hash、path、fileSize、时间戳等）
    ↓
服务端记录文件并处理 ACL、转码、CDN 等

三、阿里云 OSS 配置（V4 签名）

签名方式采用 OSS 推荐的 OSS4-HMAC-SHA256 方式，配合临时 STS Token 生成策略。

1. 权限设置

•	Bucket 必须启用 STS 签名上传权限
•	设置为 私有（防止默认公开）
•	开通 STS，创建角色绑定策略：

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "oss:PutObject",
        "oss:PostObject"
      ],
      "Resource": "acs:oss:*:*:your-bucket-name/*"
    }
  ],
  "Version": "1"
}

2. 后端生成签名参数（返回给小程序）

// 示例返回结构
{
  policy: 'base64-policy',
  signature: 'v4-hmac-sha256',
  credential: 'STS.xxx/yyyy/region/oss/aliyun_v4_request',
  date: '20250425T123456Z',
  security_token: 'token...',
  file_base_path: 'userId/familyId/album/...',
  signature_version: 'OSS4-HMAC-SHA256'
}

四、微信小程序端上传流程（功能模块拆解与封装）

第一步：调用签名接口获取上传凭证

封装为 getOssUploadPolicy.ts

const getOssUploadPolicy = async (): Promise<OssUploadConfig> => {
  const familyId = wx.getStorageSync("familiess")?.[0]?.name;
  const albumPath = wx.getStorageSync("albumUploadTarget")?.path;

  const res = await wx.requestAPI({
    method: "GET",
    url: "/families/oss/signature",
    data: { family_id: familyId, file_path: albumPath },
  });

  return res.data;
};

第二步：封装 uploadFilesToOSS

export const uploadFilesToOSS = async (files: FileWithHash[]) => {
  const urls: string[] = [];
  const metaList: any[] = [];
  const ossConfig = await getOssUploadPolicy();
  const userId = wx.getStorageSync("userInfo").id;

  for (const [index, file] of files.entries()) {
    const filename = `${Date.now()}_${index}.${getExt(file.path)}`;
    const fileKey = `${ossConfig.file_base_path}/${filename}`;

    const formData = {
      key: fileKey,
      policy: ossConfig.policy,
      "x-oss-signature-version": ossConfig.signature_version,
      "x-oss-credential": ossConfig.credential,
      "x-oss-date": ossConfig.date,
      "x-oss-signature": ossConfig.signature,
      "x-oss-security-token": ossConfig.security_token,
      success_action_status: "200"
    };

    await new Promise((resolve, reject) => {
      wx.uploadFile({
        url: "https://your-bucket.oss-cn-region.aliyuncs.com",
        filePath: file.path,
        name: "file",
        formData,
        success: (res) => {
          if (res.statusCode === 200) {
            urls.push(`${OSS_HOST}/${fileKey}`);
            metaList.push({
              album_id: albumId,
              family_id: familyId,
              file_name: filename,
              file_path: fileKey,
              object_key: file.hash,
              creator_uid: userId,
              file_type: file.type,
              file_size: file.sizeKb,
              upload_time: file.time,
              hash_value: file.hash,
            });
            resolve();
          } else reject();
        },
        fail: reject,
      });
    });
  }

  await wx.requestAPI({
    method: "POST",
    url: "/photos",
    data: { data: metaList },
  });

  return urls;
};

五、上传优化：多文件 + 秒传机制

文件秒传流程

1.	获取所有文件的 MD5 哈希（推荐使用 spark-md5）
2.	调用服务端 hash/check 接口，传入哈希数组
3.	过滤掉已上传的 hash，执行上传
4.	已上传的只需提交元信息（不重复上传）

多文件封装支持选择来源：

•	chooseMessageFile //文件更多类型 支持选择微信群组文件
•	chooseMedia // 支持拍摄

并统一格式为：

{
  path: string;
  name: string;
  size: number;
  sizeKb: number;
  time: number;
  type: "image" | "video";
  hash: string;
}

六、常见问题与坑位合集

问题	原因	解决方式
上传 403	签名不匹配	检查 credential 与 policy
图片 hash 重复	上传时间精度不足	增加 index + 毫秒后缀
file.name 为空	chooseMedia 不返回	动构造文件名
上传成功无法访问	OSS 默认私有	上传成功后调用接口公开文件或设置 ACL
多选图片顺序错乱	异步上传未 await	严格按顺序 await 或封装 Promise.allSettled()

七、总结与建议

•	建议封装上传为模块化组件，调用清晰、可复用
•	建议所有上传统一使用 V4 签名，兼容性更强
•	上传前的哈希、过滤、重命名要严格规范
•	上传成功后应尽快提交元信息并设置访问策略
•	可扩展预签名下载、防盗链、临时授权访问等高级功能

附：目录结构推荐

/utils/
  ├── getOssUploadPolicy.ts
  ├── uploadFilesToOSS.ts
  ├── computeHash.ts
  ├── fileFilter.ts
/pages/
  └── albumUploader/
        ├── index.ts
        ├── index.wxml
        ├── index.scss

结语

这篇文章是我在实际项目中从 0 到 1 完整落地「微信小程序直传阿里云 OSS」的全过程。
如果你也在做类似需求，希望这篇文章能给你一些思路与实践参考。
欢迎点赞、转发或收藏，有问题评论区见，我们一起进步。