OSS 上传工具

OSS 上传工具是一个用于处理阿里云对象存储服务（OSS）文件上传的实用工具类。它提供了文件上传、URL 签名和凭证管理等功能。

功能特点

• 文件上传进度跟踪
• 自动凭证管理和刷新
• 签名 URL 生成
• 自定义 OSS 错误处理

安装

OSS 上传工具已包含在 utils 包中，无需额外安装。

使用方法

基础文件上传

import { uploadFile } from '@/utils/oss-uploader'

const handleUpload = async (file: File) => {
  try {
    const result = await uploadFile({
      file,
      path: 'your/custom/path', // 可选，默认为 'ksh/pdf'
      getCredentials: async () => {
        // 实现获取凭证的逻辑
        return {
          accessKeyId: 'your-access-key-id',
          accessKeySecret: 'your-access-key-secret',
          securityToken: 'your-security-token'
        }
      },
      onProgress: (progress) => {
        console.log(`上传进度: ${progress.percent}%`)
      }
    })
    console.log('上传成功:', result)
  } catch (error) {
    console.error('上传失败:', error)
  }
}

生成签名 URL

import { generateSignedUrl } from '@/utils/oss-uploader'

const getFileUrl = async (objectKey: string) => {
  try {
    const url = await generateSignedUrl(
      objectKey,
      async () => {
        // 实现获取凭证的逻辑
        return {
          accessKeyId: 'your-access-key-id',
          accessKeySecret: 'your-access-key-secret',
          securityToken: 'your-security-token'
        }
      }
    )
    return url
  } catch (error) {
    console.error('生成签名 URL 失败:', error)
    throw error
  }
}

API 参考

uploadFile(options: OssConfig)

使用指定配置上传文件到 OSS。

参数

• options: OssConfig
  • file: File - 要上传的文件
  • path?: string - 自定义上传路径前缀（默认为 'ksh/pdf'）
  • onProgress?: (progress: { percent: number }) => void - 进度回调函数
  • getCredentials: () => Promise<OssCredentials> - 获取 OSS 凭证的函数
  • 其他 OSS 客户端配置选项

返回值

• Promise<OSS.MultipartUploadResult> - OSS 上传结果

generateSignedUrl(objectKey: string, getCredentials: Function, args?: Partial<OssConfig>)

生成用于访问 OSS 对象的签名 URL。

参数

• objectKey: string - OSS 中的对象键
• getCredentials: () => Promise<OssCredentials> - 获取 OSS 凭证的函数
• args?: Partial<OssConfig> - 可选的 OSS 客户端配置

返回值

• Promise<string> - 有效期为 1 小时的签名 URL

错误处理

该工具包含自定义的 OssError 类用于错误处理。所有操作都会将错误包装在此类中以实现一致的错误处理：

try {
  await uploadFile(/* ... */)
} catch (error) {
  if (error instanceof OssError) {
    // 处理 OSS 特定错误
    console.error('OSS 操作失败:', error.message)
  } else {
    // 处理其他错误
    console.error('意外错误:', error)
  }
}

配置说明

默认配置包括：

• 地域：oss-cn-hangzhou
• Bucket：yao-file-daily
• 安全传输：启用
• 超时时间：60000ms
• 已启用 CORS 并配置相应的请求头

安全注意事项

1. 永远不要在应用程序中硬编码凭证
2. 确保实现适当的凭证轮换机制
3. 使用最小必要的 OSS 权限
4. Token 默认过期时间为 15 分钟

最佳实践

1. 始终处理上传进度以提供更好的用户体验
2. 实现适当的错误处理机制
3. 使用合适的路径前缀以便于管理
4. 监控 Token 过期并及时刷新