更新记录

1.0.2（2026-01-09）

• 支持android

1.0.1（2026-01-09）

• 添加上传重试回调

1.0.0（2026-01-08）

• 首发，支持ios

平台兼容性

uni-app(4.85)

uni-app x(4.85)

UTS环境兼容性

sn-uts-alioss

阿里云 OSS（对象存储服务）UTS 插件，支持文件上传和删除功能。

功能特性

• ✅ 文件上传到 OSS（使用 STS Token）
• ✅ 上传进度回调
• ✅ 取消上传任务
• ✅ 删除单个文件
• ✅ 批量删除文件（最多1000个）
• ✅ 取消删除任务
• ✅ 自动持有 OSS Client，防止 session 失效

安装说明

1. 将 uni_modules/sn-uts-alioss 目录复制到你的 uni-app 项目的 uni_modules 目录下
2. 确保已安装阿里云 OSS iOS SDK 依赖

API 文档

类型定义

SnUtsAliossStsConfig

STS Token 配置类型

type SnUtsAliossStsConfig = {
  accessKeyId: string      // 访问密钥 ID
  accessKeySecret: string   // 访问密钥 Secret
  securityToken: string     // STS Token
  endpoint: string          // OSS 端点地址
  bucketName: string        // Bucket 名称
}

SnUtsAliossResult

操作结果类型

type SnUtsAliossResult = {
  code: number              // 状态码：0-成功，-1-失败，-2-已取消
  data: UTSJSONObject       // 结果数据
}

上传文件

uploadFile

上传文件到 OSS（使用 STS Token）

参数：

type SnUtsAliossUploadConfig = {
  stsConfig: SnUtsAliossStsConfig           // STS 配置
  objectKey: string                         // OSS 对象键（文件路径）
  filePath: string                          // 本地文件路径
  ?: (progress: number) => void   // 上传进度回调（可选，0-1）
  onRetry? : SnUtsAliossRetryCallback | null // 重试回调
  onSuccess: (result: SnUtsAliossResult) => void  // 成功回调
  onError: (result: SnUtsAliossResult) => void    // 错误回调
}

返回值： string - 任务 ID，可用于取消上传

示例：

import { uploadFile } from '@/uni_modules/sn-uts-alioss/utssdk/app-ios/index.uts'

const taskId = uploadFile({
  stsConfig: {
    accessKeyId: 'your-access-key-id',
    accessKeySecret: 'your-access-key-secret',
    securityToken: 'your-security-token',
    endpoint: 'oss-cn-hangzhou.aliyuncs.com',
    bucketName: 'your-bucket-name'
  },
  objectKey: 'uploads/image.jpg',
  filePath: '/path/to/local/file.jpg',
  : (progress) => {
    console.log(`上传进度: ${(progress * 100).toFixed(2)}%`)
  },
  onRetry: () => {
    console.log('上传重试')
  },
  onSuccess: (result) => {
    console.log('上传成功', result)
    // result.data 包含: taskId, objectKey, eTag, requestId
  },
  onError: (error) => {
    console.error('上传失败', error)
    // error.data 包含: error, taskId
  }
})

cancelUpload

取消上传任务

参数：

• taskId: string - 任务 ID（由 uploadFile 返回）

示例：

import { cancelUpload } from '@/uni_modules/sn-uts-alioss/utssdk/app-ios/index.uts'

cancelUpload(taskId)

删除文件

deleteFile

删除单个文件

参数：

type SnUtsAliossDeleteConfig = {
  stsConfig: SnUtsAliossStsConfig           // STS 配置
  objectKey: string                         // OSS 对象键（文件路径）
  onSuccess: (result: SnUtsAliossResult) => void  // 成功回调
  onError: (result: SnUtsAliossResult) => void    // 错误回调
}

返回值： string - 任务 ID，可用于取消删除

示例：

import { deleteFile } from '@/uni_modules/sn-uts-alioss/utssdk/app-ios/index.uts'

const taskId = deleteFile({
  stsConfig: {
    accessKeyId: 'your-access-key-id',
    accessKeySecret: 'your-access-key-secret',
    securityToken: 'your-security-token',
    endpoint: 'oss-cn-hangzhou.aliyuncs.com',
    bucketName: 'your-bucket-name'
  },
  objectKey: 'uploads/image.jpg',
  onSuccess: (result) => {
    console.log('删除成功', result)
    // result.data 包含: objectKey, requestId
  },
  onError: (error) => {
    console.error('删除失败', error)
    // error.data 包含: error, objectKey
  }
})

deleteMultipleFiles

批量删除文件（最多1000个）

参数：

type SnUtsAliossDeleteMultipleConfig = {
  stsConfig: SnUtsAliossStsConfig           // STS 配置
  objectKeys: string[]                      // OSS 对象键数组
  quiet?: boolean                           // 是否使用简单模式（默认true，只返回删除失败的文件）
  onSuccess: (result: SnUtsAliossResult) => void  // 成功回调
  onError: (result: SnUtsAliossResult) => void    // 错误回调
}

返回值： string - 任务 ID，可用于取消删除

quiet 模式说明：

• quiet = true（默认）：简单模式，只返回删除失败的文件列表
• quiet = false：详细模式，返回所有删除的文件列表

示例：

import { deleteMultipleFiles } from '@/uni_modules/sn-uts-alioss/utssdk/app-ios/index.uts'

const taskId = deleteMultipleFiles({
  stsConfig: {
    accessKeyId: 'your-access-key-id',
    accessKeySecret: 'your-access-key-secret',
    securityToken: 'your-security-token',
    endpoint: 'oss-cn-hangzhou.aliyuncs.com',
    bucketName: 'your-bucket-name'
  },
  objectKeys: [
    'uploads/image1.jpg',
    'uploads/image2.jpg',
    'folder/image3.jpg'
  ],
  quiet: true,  // 可选，默认 true
  onSuccess: (result) => {
    console.log('批量删除成功', result)
    // quiet=true: result.data 包含: requestId, failedObjects（失败的文件列表）
    // quiet=false: result.data 包含: requestId, deletedObjects（所有删除的文件列表）
  },
  onError: (error) => {
    console.error('批量删除失败', error)
    // error.data 包含: error, objectKeys
  }
})

cancelDelete

取消删除任务（支持单个和批量删除）

参数：

• taskId: string - 任务 ID（由 deleteFile 或 deleteMultipleFiles 返回）

示例：

import { cancelDelete } from '@/uni_modules/sn-uts-alioss/utssdk/app-ios/index.uts'

cancelDelete(taskId)

完整示例

import { 
  uploadFile, 
  cancelUpload,
  deleteFile,
  deleteMultipleFiles,
  cancelDelete
} from '@/uni_modules/sn-uts-alioss/utssdk/app-ios/index.uts'

// STS 配置
const stsConfig = {
  accessKeyId: 'your-access-key-id',
  accessKeySecret: 'your-access-key-secret',
  securityToken: 'your-security-token',
  endpoint: 'oss-cn-hangzhou.aliyuncs.com',
  bucketName: 'your-bucket-name'
}

// 1. 上传文件
const uploadTaskId = uploadFile({
  stsConfig,
  objectKey: 'uploads/photo.jpg',
  filePath: '/path/to/photo.jpg',
  : (progress) => {
    console.log(`上传进度: ${(progress * 100).toFixed(2)}%`)
  },
  onSuccess: (result) => {
    console.log('上传成功', result.data)
  },
  onError: (error) => {
    console.error('上传失败', error.data)
  }
})

// 如果需要取消上传
// cancelUpload(uploadTaskId)

// 2. 删除单个文件
const deleteTaskId = deleteFile({
  stsConfig,
  objectKey: 'uploads/photo.jpg',
  onSuccess: (result) => {
    console.log('删除成功', result.data)
  },
  onError: (error) => {
    console.error('删除失败', error.data)
  }
})

// 如果需要取消删除
// cancelDelete(deleteTaskId)

// 3. 批量删除文件
const deleteMultipleTaskId = deleteMultipleFiles({
  stsConfig,
  objectKeys: ['file1.jpg', 'file2.jpg', 'file3.jpg'],
  quiet: true,
  onSuccess: (result) => {
    console.log('批量删除成功', result.data)
    if (result.data.failedObjects) {
      console.log('删除失败的文件:', result.data.failedObjects)
    }
  },
  onError: (error) => {
    console.error('批量删除失败', error.data)
  }
})

// 如果需要取消批量删除
// cancelDelete(deleteMultipleTaskId)

注意事项

1. STS Token 安全

   • STS Token 具有时效性，建议在服务端生成并定期刷新
   • 不要在前端代码中硬编码 AccessKey，应使用 STS Token

2. 文件路径

   • filePath 支持相对路径和绝对路径
   • 相对路径会自动转换为绝对路径

3. 批量删除限制

   • 批量删除最多支持 1000 个文件
   • 超过限制会返回错误

4. 任务管理

   • 所有任务都会自动持有 OSS Client，防止 session 失效
   • 任务完成后会自动清理，无需手动管理

5. 错误处理

   • 所有操作都通过回调返回结果
   • code = 0 表示成功，code = -1 表示失败，code = -2 表示已取消
   • 错误信息在 result.data.error 中

6. 线程安全

   • 所有回调都会在主线程执行，可以直接更新 UI

参考文档

• 阿里云 OSS android SDK 文档
• 阿里云 OSS iOS SDK 文档