@gyjshow/cos-upload

小程序直传腾讯 COS

特点

• 不依赖 cos-wx-sdk-v5 — 纯 JS 签名，无平台依赖
• 全平台自动适配 — 微信 / 小红书 / 抖音 / 支付宝 / 百度 / QQ
• 签名核心从官方 SDK 提取 — 与 cos-wx-sdk-v5 签名算法完全一致
• 体积小 — 两个文件共约 28KB

支持平台

| 平台 | 全局对象 | 自动检测 | |---|---|---| | 微信 | wx.* | ✅ | | 小红书 | xhs.* | ✅ | | 抖音（字节跳动） | tt.* | ✅ | | 支付宝 | my.* | ✅ | | 百度 | swan.* | ✅ | | QQ | qq.* | ✅ |

安装

# scoped package，发布时需要 --access public
npm install @gyjshow/cos-upload

# 或本地安装
npm install /path/to/repo

使用

const { uploadToCOS, fetchSTS } = require('@gyjshow/cos-upload');

// 1. 从后端获取 STS 临时密钥
const stsData = await fetchSTS('https://your-api.com/sts');
// stsData = { TempSecretId, TempSecretKey, SecurityToken }

// 2. 上传到 COS（各平台通用）
try {
  const result = await uploadToCOS({
    tempFilePath: tempFilePath,                // 各平台返回的临时文件路径
    fileName: 'xxx.png',                        // COS 上的文件名
    stsData: stsData,                           // 后端 STS 数据
    bucket: 'your-bucket-125xxxxx',             // COS 存储桶
    region: 'ap-guangzhou',                     // COS 地域
    folder: 'images/share',                     // COS 目录（可选）
    domain: 'upload.ichibankuji.cn',            // 自定义上传域名（可选，默认使用 COS 端点）
  });
  console.log('上传成功', result);
  // result.key  = "images/share/xxx.png"
  // result.url  = "https://upload.ichibankuji.cn/images/share/xxx.png"
  // result.timings = { param: 0, sign: 2, http: 200, total: 208 }
} catch (err) {
  console.log('上传失败', err);
}

各平台路径示例

| 平台 | tempFilePath 示例 | |---|---| | 微信 | wxfile://tmp/xxx.png | | 小红书 | xhsfile://tmp/xxx.png | | 抖音 | ttfile://tmp/xxx.png |

API

uploadToCOS(options)

| 参数 | 必填 | 说明 | |---|---|---| | tempFilePath | ✓ | 小程序图片选择器返回的临时路径 | | fileName | ✓ | 上传到 COS 的文件名（含扩展名） | | stsData | ✓ | 后端 STS 接口返回的对象 { TempSecretId, TempSecretKey, SecurityToken } | | bucket | ✓ | COS 存储桶名称（含 AppId，如 test-1250000000） | | region | ✓ | COS 地域（如 ap-guangzhou） | | folder | ✗ | COS 目录，无前导斜杠（如 images/share） | | domain | ✗ | 自定义上传域名（如 upload.ichibankuji.cn），默认 {bucket}.cos.{region}.myqcloud.com | | contentType | ✗ | 强制指定 Content-Type，默认根据 fileName 后缀推断 | | timeout | ✗ | 上传超时时间，默认 30000（毫秒） |

返回 Promise<{ success, data, key, url, timings }>

• timings: { param, sign, http, total } 各阶段耗时（毫秒）

fetchSTS(stsUrl)

传入 STS 接口地址，自动请求并返回 { TempSecretId, TempSecretKey, SecurityToken }

getAuth(opt)

纯签名函数，可直接用于生成 COS Authorization。

原理

1. 自动检测当前小程序平台（微信 / 小红书 / 抖音 / 支付宝 / 百度 / QQ）
2. getAuth() → 计算 COS PostObject 签名
3. uploadFile(url, filePath, formData) → POST + multipart/form-data → 直传 COS
   （使用 COS PostObject 协议，签名放入 formData.Signature 字段）

注意事项

• Key 不带前导 /，例如 images/share/xxx.png ✅
• 签名有效期默认 900 秒（15 分钟）
• STS 过期前请重新获取新密钥
• 自定义上传域名 domain 通过 COS 自定义域名/CDN 加速上传
• 上传使用 uploadFile API（wx.uploadFile / xhs.uploadFile），不走 request 直传。 小红书真机的 xhs.request 会将传入的 ArrayBuffer/Uint8Array 转为 String 再发送， 无法用于二进制直传。因此使用 PostObject + multipart/form-data 协议上传。