更新记录

1.0.1（2026-05-20）

修复回调问题

1.0.0（2026-05-20）

• 初始版本，支持阿里云OSS STS直传上传

平台兼容性

uni-app(4.81)

RD阿里云OSS直传插件

基于阿里云OSS官方SDK的客户端直传UTS插件，支持多种认证模式、上传/下载、进度回调、断点续传等功能。

平台支持

安装

将 rd-oss 目录放入项目的 uni_modules 文件夹即可。

iOS 平台依赖通过 CocoaPods 自动引入 AliyunOSSiOS，云打包时无需手动配置。

快速开始

1. 初始化

根据你的认证方式选择对应的初始化方法：

AK 模式（开发测试用）

import { initWithAK } from '@/uni_modules/rd-oss'

initWithAK({
  endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
  accessKeyId: 'your-access-key-id',
  accessKeySecret: 'your-access-key-secret'
})

⚠️ AK 模式直接使用永久 AccessKey，仅建议开发测试环境使用，生产环境请使用 STS 模式。

STS 模式（推荐）

import { initWithSTS } from '@/uni_modules/rd-oss'

initWithSTS({
  endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
  accessKeyId: 'sts-access-key-id',        // STS 临时 AK
  accessKeySecret: 'sts-access-key-secret', // STS 临时 SK
  securityToken: 'sts-security-token'       // STS SecurityToken
})

2. 注册回调

import { onSuccess, , onError } from '@/uni_modules/rd-oss'

// 上传成功回调
onSuccess((objectKey, etag, responseUrl) => {
  console.log('上传成功:', objectKey, etag, responseUrl)
})

// 上传进度回调（自动节流，最低间隔 50ms）
((bytesSent, totalBytes, percent) => {
  console.log(`进度: ${(percent * 100).toFixed(1)}%`)
})

// 错误回调
onError((errMsg) => {
  console.error('错误:', errMsg)
})

3. 上传文件

简单上传（小文件）

import { putObject } from '@/uni_modules/rd-oss'

putObject({
  bucketName: 'your-bucket',
  objectKey: 'test/photo.jpg',
  filePath: '/path/to/local/file.jpg',
  contentType: 'image/jpeg',          // 可选
  customMeta: { 'author': 'rd' }      // 可选，自定义元数据
})

分片上传（大文件，支持并发）

import { multipartUpload } from '@/uni_modules/rd-oss'

multipartUpload({
  bucketName: 'your-bucket',
  objectKey: 'videos/demo.mp4',
  filePath: '/path/to/large-file.mp4',
  partSize: 262144,                   // 可选，分片大小（字节），默认 256KB
  contentType: 'video/mp4',           // 可选
  customMeta: { 'author': 'rd' },     // 可选
  threadNum: 5                        // 可选，并发数，默认 5
})

断点续传上传

import { resumableUpload } from '@/uni_modules/rd-oss'

resumableUpload({
  bucketName: 'your-bucket',
  objectKey: 'videos/demo.mp4',
  filePath: '/path/to/large-file.mp4',
  partSize: 262144,                           // 可选，分片大小，默认 256KB
  contentType: 'video/mp4',                   // 可选
  customMeta: { 'author': 'rd' },             // 可选
  recordDirectoryPath: '/path/to/record/dir'  // 可选，断点记录保存目录，默认临时目录
})

4. 下载文件

import { getObject, onDownloadSuccess, onDownloadProgress } from '@/uni_modules/rd-oss'

// 注册下载回调
onDownloadSuccess((objectKey, filePath) => {
  console.log('下载成功:', objectKey, filePath)
})

onDownloadProgress((bytesWritten, totalBytes, percent) => {
  console.log(`下载进度: ${(percent * 100).toFixed(1)}%`)
})

// 执行下载
getObject({
  bucketName: 'your-bucket',
  objectKey: 'test/photo.jpg',
  filePath: '/path/to/save/photo.jpg'
})

5. 生成签名URL

import { presignUrl } from '@/uni_modules/rd-oss'

const url = presignUrl({
  bucketName: 'your-bucket',
  objectKey: 'test/photo.jpg',
  expires: 3600,          // 可选，过期时间（秒），默认 3600
  httpMethod: 'GET'       // 可选，HTTP 方法，默认 GET
})

console.log('签名URL:', url)

6. 取消当前任务

import { cancelCurrentTask } from '@/uni_modules/rd-oss'

cancelCurrentTask()

API 参考

初始化

上传

下载

工具

回调注册

类型定义

// AK 配置
type AKConfig = {
  endpoint: string
  accessKeyId: string
  accessKeySecret: string
}

// STS 配置
type OSSConfig = {
  endpoint: string
  accessKeyId: string
  accessKeySecret: string
  securityToken: string
}

// 简单上传选项
type UploadOptions = {
  bucketName: string
  objectKey: string
  filePath: string
  contentType?: string
  customMeta?: Map<string, string>
}

// 分片上传选项
type MultipartUploadOptions = {
  bucketName: string
  objectKey: string
  filePath: string
  partSize?: number           // 默认 262144 (256KB)
  contentType?: string
  customMeta?: Map<string, string>
  threadNum?: number          // 默认 5
}

// 断点续传选项
type ResumableUploadOptions = {
  bucketName: string
  objectKey: string
  filePath: string
  partSize?: number           // 默认 262144 (256KB)
  contentType?: string
  customMeta?: Map<string, string>
  recordDirectoryPath?: string // 默认临时目录
}

// 下载选项
type DownloadOptions = {
  bucketName: string
  objectKey: string
  filePath: string
}

// 签名URL选项
type PresignUrlOptions = {
  bucketName: string
  objectKey: string
  expires?: number            // 默认 3600 (秒)
  httpMethod?: string         // 默认 "GET"
}

注意事项

1. endpoint 格式：需包含协议前缀，如 https://oss-cn-hangzhou.aliyuncs.com
2. 文件路径：支持 file:// URL 和普通路径两种格式
3. 自定义元数据：上传时传入的 customMeta 会自动添加 x-oss-meta- 前缀
4. 进度节流：上传/下载进度回调自动节流（最低 50ms 间隔），完成时强制推送最后一次
5. 任务管理：同一时间只追踪一个任务，新任务会覆盖旧任务的取消令牌
6. 断点续传：取消时会自动清理上传记录（deleteUploadIdOnCancelling = true）

性能特性

• os_unfair_lock 零分配锁，线程安全读写
• 热路径方法 @inline(__always) 强制内联
• 进度数值在子线程预计算，减少主线程开销
• final class 禁止继承，启用静态派发