更新记录

1.0.0（2025-10-16） 下载此版本

首次发布

平台兼容性

其他

Ali-OSS Upload 模块

一个专为 uni-app 设计的阿里云 OSS 文件直传模块，支持自定义表单数据、文件重命名、目录管理等功能。

功能特性

• ✅ 简单易用：一行代码完成文件上传
• ✅ 自动签名：自动生成 OSS 上传签名
• ✅ 文件重命名：支持自定义文件名
• ✅ 目录管理：支持文件分类存储
• ✅ 自定义表单：支持传入自定义表单数据
• ✅ 类型安全：完整的 TypeScript 类型定义
• ✅ 错误处理：完善的参数验证和错误提示

安装使用

npm i uniapp-oss-upload

1. 导入模块

import { ossUpload } from "uniapp-oss-upload";

2. 基础使用

// 最简单的使用方式
ossUpload({
  filePath: "/path/to/your/file.jpg",
  url: "oss-cn-hangzhou.aliyuncs.com",
  bucket: "your-bucket-name",
  OSSAccessKeyId: "your-access-key-id",
  OssAccesskeySercet: "your-access-key-secret",
}).then((result) => {
  console.log("上传成功，文件URL：", result.data);
})
.catch((err) => {
    console.error("上传失败：", err.data);
})
.finally(() => {
    uni.hideLoading();
});

API 文档

OssUploadParams 接口

OssUploadResult 接口

使用示例

1. 基础文件上传

try {
  const result = await ossUpload({
    filePath: "/path/to/image.jpg",
    url: "oss-cn-hangzhou.aliyuncs.com",
    bucket: "my-bucket",
    OSSAccessKeyId: "LTAI5t...",
    OssAccesskeySercet: "your-secret-key",
  });

  if (result.success) {
    console.log("文件上传成功：", result.data);
  }
} catch (error) {
  console.error("上传失败：", error);
}

2. 自定义文件名和目录

const result = await ossUpload({
  filePath: "/path/to/photo.jpg",
  name: "avatar.jpg", // 自定义文件名
  dir: "users/avatars/", // 存储目录
  url: "oss-cn-hangzhou.aliyuncs.com",
  bucket: "my-bucket",
  OSSAccessKeyId: "LTAI5t...",
  OssAccesskeySercet: "your-secret-key",
});

3. 使用自定义表单数据

const result = await ossUpload({
  filePath: "/path/to/document.pdf",
  dir: "documents/",
  url: "oss-cn-hangzhou.aliyuncs.com",
  bucket: "my-bucket",
  OSSAccessKeyId: "LTAI5t...",
  OssAccesskeySercet: "your-secret-key",
  customFormData: {
    // 设置文件内容类型
    "x-oss-content-type": "application/pdf",
    // 设置缓存控制
    "x-oss-cache-control": "max-age=3600",
    // 添加自定义元数据
    "x-oss-meta-author": "John Doe",
    "x-oss-meta-description": "Important document",
    // 设置对象标签
    "x-oss-tagging": "category=document&type=pdf",
    // 设置存储类型
    "x-oss-storage-class": "Standard",
  },
});

4. 在 Vue 组件中使用

<template>
  <view>
    <button @click="chooseAndUpload">选择并上传文件</button>
    <view v-if="uploadResult">
      <text>上传结果：{{ uploadResult }}</text>
    </view>
  </view>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { ossUpload } from "@/common/ali-upload";

const uploadResult = ref("");

const chooseAndUpload = async () => {
  try {
    // 选择文件
    const res = await uni.chooseImage({
      count: 1,
      sourceType: ["album", "camera"],
    });

    if (res.tempFilePaths && res.tempFilePaths.length > 0) {
      const filePath = res.tempFilePaths[0];

      // 上传文件
      const result = await ossUpload({
        filePath,
        dir: "uploads/",
        url: "oss-cn-hangzhou.aliyuncs.com",
        bucket: "my-bucket",
        OSSAccessKeyId: "LTAI5t...",
        OssAccesskeySercet: "your-secret-key",
      });

      if (result.success) {
        uploadResult.value = `上传成功：${result.data}`;
      } else {
        uploadResult.value = `上传失败：${result.data}`;
      }
    }
  } catch (error) {
    uploadResult.value = `选择文件失败：${error}`;
  }
};
</script>

支持的 OSS 自定义字段

通过 customFormData 参数，你可以设置以下 OSS 支持的字段：

内容类型和编码

• x-oss-content-type: 设置文件 MIME 类型
• x-oss-content-encoding: 设置内容编码
• x-oss-content-disposition: 设置下载时的文件名

缓存控制

• x-oss-cache-control: 设置缓存控制策略
• x-oss-expires: 设置过期时间

元数据

• x-oss-meta-*: 自定义元数据（如：x-oss-meta-author、x-oss-meta-description）

对象标签

• x-oss-tagging: 设置对象标签（格式：key1=value1&key2=value2）

存储和加密

• x-oss-storage-class: 存储类型（Standard、IA、Archive）
• x-oss-server-side-encryption: 服务端加密
• x-oss-server-side-encryption-key-id: 加密密钥 ID

访问控制

• x-oss-object-acl: 对象访问权限（private、public-read、public-read-write）

错误处理

模块会进行以下参数验证：

• 文件路径不能为空
• OSS URL 不能为空
• OSS Bucket 不能为空
• OSS AccessKeyId 不能为空
• OSS AccessKeySecret 不能为空

try {
  const result = await ossUpload({
    // ... 参数
  });

  if (result.success) {
    // 处理成功情况
    console.log("文件URL：", result.data);
  } else {
    // 处理失败情况
    console.error("上传失败：", result.data);
  }
} catch (error) {
  // 处理异常情况
  console.error("发生异常：", error);
}

注意事项

1. 安全性：请勿在前端代码中硬编码 AccessKey 和 Secret，建议通过后端接口获取临时凭证
2. 文件大小：默认限制文件大小为 1GB，如需修改请调整 policyText 中的 content-length-range
3. 目录格式：目录参数应以 / 结尾，如 'images/'
4. URL 格式：支持完整 URL 和域名两种格式
5. 文件名：如果不指定 name 参数，系统会自动生成随机文件名

技术实现

• 使用 HMAC-SHA1 算法生成签名
• 支持 Base64 编码
• 兼容 uni-app 的 uni.uploadFile API
• 完整的 TypeScript 类型支持

许可证

MIT License