ejoy-ali-oss-upload

简介

ejoy-ali-oss-upload 是一个轻量级的工具库，专为前端项目提供阿里云OSS图片上传功能。该库使用PostObject方式实现文件上传，支持STS临时授权，并提供完整的TypeScript类型支持。

功能特性

• ✅ 支持阿里云OSS图片上传（JPEG、JPG、PNG、WebP格式）
• ✅ 使用PostObject方式上传，适合浏览器环境
• ✅ 支持STS临时授权方式
• ✅ 文件类型和大小验证
• ✅ 完整的TypeScript类型支持
• ✅ 友好的错误处理和提示
• ✅ ESM模块格式，支持现代前端项目

安装指南

使用npm安装:

npm install ejoy-ali-oss-upload

使用yarn安装:

yarn add ejoy-ali-oss-upload

使用pnpm安装:

pnpm add ejoy-ali-oss-upload

使用说明

基本用法

import { uploadImageToOSS } from 'ejoy-ali-oss-upload';

// 假设您已经从服务端获取了STS授权信息
const stsResponse = {
  ossEndpoint: 'oss-cn-beijing.aliyuncs.com',
  bucketName: 'your-bucket-name',
  accessKeyId: 'STS.your-access-key-id',
  accessKeySecret: 'your-access-key-secret',
  securityToken: 'your-security-token',
  expiration: '2025-08-05T12:00:00Z',
  path: 'uploads/images'
};

// 文件上传示例
async function handleFileUpload(file) {
  try {
    // 可选的OSS前缀，用于构建完整的文件URL
    const ossPrefix = 'https://your-bucket-name.oss-cn-beijing.aliyuncs.com/';
    
    const result = await uploadImageToOSS(file, stsResponse, ossPrefix);
    
    if (result.success) {
      console.log('上传成功，文件URL:', result.url);
      return result.url;
    } else {
      console.error('上传失败:', result.error);
      return null;
    }
  } catch (error) {
    console.error('上传过程发生错误:', error);
    return null;
  }
}

// 在表单提交或文件选择事件中使用
document.getElementById('fileInput').addEventListener('change', async (e) => {
  const file = e.target.files[0];
  if (file) {
    const imageUrl = await handleFileUpload(file);
    if (imageUrl) {
      // 处理上传成功的逻辑
    }
  }
});

TypeScript类型

// 导入类型
import { UploadStsResponse, UploadResult } from 'ejoy-ali-oss-upload';

// STS响应类型
const stsResponse: UploadStsResponse = {
  ossEndpoint: 'oss-cn-beijing.aliyuncs.com',
  bucketName: 'your-bucket-name',
  accessKeyId: 'STS.your-access-key-id',
  accessKeySecret: 'your-access-key-secret',
  securityToken: 'your-security-token',
  expiration: '2025-08-05T12:00:00Z',
  path: 'uploads/images'
};

// 处理上传结果
async function handleUpload(file: File): Promise<string | null> {
  const result: UploadResult = await uploadImageToOSS(file, stsResponse, prefix);
  
  if (result.success && result.url) {
    return result.url;
  }
  
  return null;
}

注意事项

1. 该库仅支持图片文件上传（JPEG、JPG、PNG、WebP格式）
2. 文件大小限制为10MB
3. 需要从服务端获取有效的STS授权信息
4. 上传前会自动验证文件类型和大小

贡献方式

欢迎对本项目进行贡献！您可以通过以下方式参与：

1. 提交Issue报告bug或提出新功能建议
2. 提交Pull Request改进代码
3. 完善文档和示例

开发指南

克隆项目并安装依赖：

git clone https://github.com/CorScorpii-WY/ejoy-ali-oss-upload.git
cd ejoy-ali-oss-upload
npm install

开发模式：

npm run dev

构建项目：

npm run build

许可证信息

本项目采用ISC许可证。

联系方式

如有任何问题或建议，请通过以下方式联系我们：

• 项目Issues: https://github.com/CorScorpii-WY/ejoy-ali-oss-upload/issues
• 电子邮件: [email protected]

© 2025 ejoy-ali-oss-upload. 保留所有权利。