阿里云OSS上传工具库文档

1. 功能概述

本工具库提供了与阿里云OSS（对象存储服务）交互的核心功能，主要用于文件上传操作。通过预签名URL或STS Token方式，实现前端直传文件到OSS，无需经过应用服务器中转，提高上传效率。

2. 核心概念说明

预签名URL：由后端生成的临时URL，包含认证信息，前端可以直接使用该URL上传文件到OSS
STS Token：阿里云安全令牌服务生成的临时访问凭证，包含AccessKeyId、AccessKeySecret和SecurityToken
直传模式：前端直接将文件上传到OSS，不经过应用服务器中转

3. 模块结构与逻辑关系

3.1 模块依赖关系

├── 外部依赖
│   ├── axios：用于HTTP请求
│   └── ../api/aigc：包含OSS相关API接口
├── 配置常量
│   └── ALIOSS_CONFIG：OSS基础配置
├── 核心API调用函数
│   ├── getAliOSSPresignUrl：获取预签名URL
│   ├── getSTSToken：获取STS临时凭证
│   └── getDirectUploadUrl：获取直传URL
├── 上传方法实现
│   ├── uploadToAliOSS：基础上传方法
│   ├── elUploadToAliOSS：适配Element UI的上传方法
│   ├── directUpload：小文件直传
│   ├── uploadWithSTSToken：STS Token方式上传
│   ├── uploadWithPresignedUrl：预签名URL方式上传
│   └── largeFileUpload：大文件上传推荐方案
└── 测试工具
    └── testAliOSSPresignUrl：测试OSS签名接口

3.2 调用关系图

[客户端] --> [上传组件] --> [elUploadToAliOSS] --> [uploadToAliOSS] --> [getAliOSSPresignUrl] --> [OSS API]
                              |
                              v
                        [直接上传方法] --> [uploadWithPresignedUrl] --> [getDirectUploadUrl] --> [OSS API]
                              |
                              v
                        [uploadWithSTSToken] --> [getSTSToken] --> [OSS API]

4. 实现方法详细说明

4.1 配置常量

ALIOSS_CONFIG

javascript

/**
 * 阿里云OSS配置
 */
export const ALIOSS_CONFIG = {
  action: '', // 从签名接口获取
  accept: 'image/jpg,image/png,image/jpeg,image/gif,video/mp4,audio/wav,audio/mp3'
}

4.2 核心API调用函数

getAliOSSPresignUrl

javascript

/**
 * 获取OSS上传签名URL
 * @param params 上传参数
 * @returns {Promise<*>}
 * @example
 * getAliOSSPresignUrl({
 *   fileName: 'example.jpg',
 *   fileType: 'image/jpeg',
 *   fileSize: 1024000,
 *   businessType: 'aigc'
 * })
 */
export async function getAliOSSPresignUrl (params = {
  fileName: '',
  fileType: 'image/jpeg',
  fileSize: 0,
  businessType: 'aigc'
})

getSTSToken

javascript

/**
 * 获取OSS临时访问凭证(STS Token)
 * @param options 配置选项
 * @returns {Promise<*>}
 */
export async function getSTSToken (options = {})

getDirectUploadUrl

javascript

/**
 * 获取OSS直传文件的临时URL
 * @param params 请求参数
 * @returns {Promise<*>}
 */
export async function getDirectUploadUrl (params)

4.3 文件上传方法

uploadToAliOSS

javascript

/**
 * 上传文件到阿里云OSS
 * @param file 文件对象
 * @param options 上传选项
 * @returns {Promise<*>}
 * @example
 * uploadToAliOSS(file, {
 *   businessType: 'aigc',
 *   onProgress: (e) => console.log('上传进度:', e.loaded/e.total*100+'%')
 * })
 */
export async function uploadToAliOSS (file, options = {})

elUploadToAliOSS

javascript

/**
 * 覆盖el-upload组件默认的上传行为
 * @param upload el-upload的上传对象
 * @param options 上传选项
 */
export function elUploadToAliOSS (upload, options = {})

directUpload

javascript

/**
 * 小文件直传模式
 * @param file 文件对象
 * @param params 请求参数
 * @returns {Promise<*>}
 */
export async function directUpload (file, params)

uploadWithSTSToken

javascript

/**
 * 使用STS Token直接上传文件到OSS
 * 注意：实际使用时，建议通过后端服务生成预签名URL进行上传，而不是在前端直接使用STS Token进行签名计算
 * @param file 文件对象
 * @param bucket OSS桶名
 * @param key 文件名/路径
 * @param region OSS区域，默认oss-cn-shenzhen
 * @param options 上传选项
 * @returns {Promise<*>}
 */
export async function uploadWithSTSToken(file, bucket, key, region = 'oss-cn-shenzhen', options = {})

uploadWithPresignedUrl

javascript

/**
 * 使用预签名URL上传文件
 * @param file 文件对象
 * @param params 请求参数
 * @param options 上传选项
 * @returns {Promise<*>}
 * @example
 * uploadWithPresignedUrl(file, {
 *   bucket: 'my-bucket',
 *   key: 'uploads/example.jpg',
 *   region: 'oss-cn-shenzhen',
 *   expires: 3600
 * }, {
 *   onProgress: (e) => console.log('上传进度:', e.loaded/e.total*100+'%')
 * })
 */
export async function uploadWithPresignedUrl(file, params, options = {})

largeFileUpload

javascript

/**
 * 大文件上传推荐方案（前端分片）
 * @param file 文件对象
 * @param params 请求参数
 * @param options 上传选项
 * @returns {Promise<*>}
 */
export async function largeFileUpload(file, params, options = {})

4.4 测试工具

testAliOSSPresignUrl

javascript

/**
 * 测试OSS签名接口
 * @returns {Promise<void>}
 */
export async function testAliOSSPresignUrl ()

5. 使用场景指南

5.1 基础上传场景

适用场景：普通文件上传，适用于大多数情况

推荐方法：uploadToAliOSS

javascript

import { uploadToAliOSS } from '@/utils/ali-oss';

async function handleFileUpload(file) {
  try {
    const result = await uploadToAliOSS(file, {
      businessType: 'aigc',
      onProgress: (e) => {
        const percent = Math.round((e.loaded / e.total) * 100);
        console.log(`上传进度：${percent}%`);
      }
    });
    console.log('上传成功，文件URL：', result.url);
    return result.url;
  } catch (error) {
    console.error('上传失败：', error);
  }
}

5.2 Element UI上传组件集成

适用场景：使用Element UI的el-upload组件进行文件上传

推荐方法：elUploadToAliOSS

javascript

import { elUploadToAliOSS } from '@/utils/ali-oss';

// 在el-upload组件的http-request属性中使用
const uploadOptions = {
  businessType: 'aigc'
};

// 组件配置示例
// <el-upload
//   :http-request="(upload) => elUploadToAliOSS(upload, uploadOptions)"
// >
//   <el-button>点击上传</el-button>
// </el-upload>

5.3 预签名URL上传

适用场景：需要灵活控制上传参数（如过期时间、存储路径等）

推荐方法：uploadWithPresignedUrl

javascript

import { uploadWithPresignedUrl } from '@/utils/ali-oss';

async function handlePresignedUpload(file) {
  try {
    const result = await uploadWithPresignedUrl(file, {
      bucket: 'my-bucket',
      key: `uploads/${Date.now()}-${file.name}`,
      region: 'oss-cn-shenzhen',
      expires: 3600
    });
    console.log('上传成功，文件URL：', result.url);
    return result.url;
  } catch (error) {
    console.error('上传失败：', error);
  }
}

5.4 大文件上传

适用场景：上传较大文件（目前后端未提供分片合并接口，实际调用预签名URL上传）

推荐方法：largeFileUpload

javascript

import { largeFileUpload } from '@/utils/ali-oss';

async function handleLargeFileUpload(file) {
  try {
    const result = await largeFileUpload(file, {
      bucket: 'my-bucket',
      key: `large-uploads/${file.name}`,
      region: 'oss-cn-shenzhen'
    }, {
      onProgress: (e) => {
        const percent = Math.round((e.loaded / e.total) * 100);
        console.log(`上传进度：${percent}%`);
      }
    });
    console.log('上传成功，文件URL：', result.url);
    return result.url;
  } catch (error) {
    console.error('上传失败：', error);
  }
}

6. 常见问题与注意事项

6.1 安全注意事项

不推荐前端直接使用STS Token进行签名计算：由于前端环境的安全性限制，AccessKeySecret可能被泄露
建议使用后端生成预签名URL：本工具库中的uploadWithSTSToken方法内部也会调用uploadWithPresignedUrl方法
设置合理的URL过期时间：通过expires参数控制预签名URL的有效期，默认3600秒（1小时）

6.2 错误处理

所有方法都包含完善的错误处理机制，会捕获并记录异常
建议在调用时使用try/catch捕获可能的错误，并提供用户友好的提示
常见错误包括：签名失败、网络错误、上传超时等

6.3 浏览器兼容性

支持所有现代浏览器（Chrome、Firefox、Safari、Edge等）
对于IE浏览器，可能需要额外的polyfill支持Promise和Fetch API

6.4 大文件上传限制

当前后端未提供分片合并接口，大文件上传功能受限
对于特别大的文件（如超过100MB），建议咨询后端添加分片合并接口

7. 完整API导出

工具库默认导出包含所有方法的对象，方便整体引入：

javascript

export default {
  getAliOSSPresignUrl,
  uploadToAliOSS,
  elUploadToAliOSS,
  testAliOSSPresignUrl,
  CONFIG: ALIOSS_CONFIG,
  getSTSToken,
  getDirectUploadUrl,
  directUpload,
  uploadWithSTSToken,
  uploadWithPresignedUrl,
  largeFileUpload
}

阿里云OSS上传工具库文档 ​

1. 功能概述 ​

2. 核心概念说明 ​

3. 模块结构与逻辑关系 ​

3.1 模块依赖关系 ​

3.2 调用关系图 ​

4. 实现方法详细说明 ​

4.1 配置常量 ​

ALIOSS_CONFIG ​

4.2 核心API调用函数 ​

getAliOSSPresignUrl ​

getSTSToken ​

getDirectUploadUrl ​

4.3 文件上传方法 ​

uploadToAliOSS ​

elUploadToAliOSS ​

directUpload ​

uploadWithSTSToken ​

uploadWithPresignedUrl ​

largeFileUpload ​

4.4 测试工具 ​

testAliOSSPresignUrl ​

5. 使用场景指南 ​

5.1 基础上传场景 ​

5.2 Element UI上传组件集成 ​

5.3 预签名URL上传 ​

5.4 大文件上传 ​

6. 常见问题与注意事项 ​

6.1 安全注意事项 ​

6.2 错误处理 ​

6.3 浏览器兼容性 ​

6.4 大文件上传限制 ​

7. 完整API导出 ​

阿里云OSS上传工具库文档

1. 功能概述

2. 核心概念说明

3. 模块结构与逻辑关系

3.1 模块依赖关系

3.2 调用关系图

4. 实现方法详细说明

4.1 配置常量

ALIOSS_CONFIG

4.2 核心API调用函数

getAliOSSPresignUrl

getSTSToken

getDirectUploadUrl

4.3 文件上传方法

uploadToAliOSS

elUploadToAliOSS

directUpload

uploadWithSTSToken

uploadWithPresignedUrl

largeFileUpload

4.4 测试工具

testAliOSSPresignUrl

5. 使用场景指南

5.1 基础上传场景

5.2 Element UI上传组件集成

5.3 预签名URL上传

5.4 大文件上传

6. 常见问题与注意事项

6.1 安全注意事项

6.2 错误处理

6.3 浏览器兼容性

6.4 大文件上传限制

7. 完整API导出