@wecode-team/oss

We0 OSS SDK —— 通过 sessionId 上传、下载、删除文件，支持阿里云 OSS，内置图片压缩、类型校验、并发上传。

安装

npm install @wecode-team/oss
# or
pnpm add @wecode-team/oss

快速开始

import { createOssClient } from "@wecode-team/oss"

const oss = createOssClient()

// 上传文件
const { url } = await oss.upload("session-id", file, "photo.jpg")

// 获取文件 URL
const fileUrl = await oss.getFileUrl("session-id", "photo.jpg")

// 列出文件
const files = await oss.listFiles("session-id")

// 删除文件
await oss.delete("session-id", "photo.jpg")

默认连接 https://we0.ai，自部署时传 createOssClient({ baseURL: "https://your-domain.com" })。

API

createOssClient(options?)

创建客户端实例。

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | baseURL | string | "https://we0.ai" | API 基础地址 | | timeout | number | 30000 | 请求超时（ms） | | retry | RetryOptions | { retries: 2, delay: 1000 } | 重试配置 | | compress | CompressOptions \| false | 见下方 | 图片压缩配置 | | limits | SizeLimits | 见下方 | 文件大小限制 | | allowedExtensions | Set<string> | 内置白名单 | 允许的文件扩展名 |

oss.upload(sessionId, file, fileName, options?)

上传单个文件。自动执行：图片压缩 → 类型校验（白名单 + 魔数防伪造）→ 大小校验 → 上传。

file 支持的输入类型：

| 类型 | 场景 | |------|------| | File / Blob | 浏览器原生 | | ArrayBuffer | 通用 | | Uint8Array / Buffer | Node.js | | string | 文本内容，自动 UTF-8 编码 |

options：

| 参数 | 类型 | 说明 | |------|------|------| | compress | CompressOptions \| false | 压缩配置，false 关闭 | | rename | boolean \| string \| (name) => string | 重命名 | | onProgress | ({ loaded, total, percent }) => void | 进度回调（浏览器） | | skipValidation | boolean | 跳过类型校验 | | retry | RetryOptions | 重试配置 |

// 自动 UUID 重命名
await oss.upload("sid", file, "photo.jpg", { rename: true })
// → 上传为 "a3f8c2e1-xxxx.jpg"

// 自定义文件名
await oss.upload("sid", file, "photo.jpg", { rename: "avatar.jpg" })

// 关闭压缩上传原图
await oss.upload("sid", file, "photo.png", { compress: false })

// 上传进度（浏览器）
await oss.upload("sid", file, "video.mp4", {
  onProgress: ({ percent }) => console.log(`${percent}%`),
})

oss.uploadBatch(sessionId, files, options?)

批量并发上传。

const results = await oss.uploadBatch("session-id", [
  { file: img1, fileName: "a.jpg" },
  { file: img2, fileName: "b.png" },
  { file: doc, fileName: "c.pdf" },
], {
  concurrency: 3,        // 最大并发数，默认 3
  continueOnError: true, // 某个失败继续上传其余，默认 true
})

// results: [{ fileName, success, result?, error? }, ...]

oss.delete(sessionId, fileName)

删除指定文件。

oss.getFileUrl(sessionId, fileName)

获取单个文件的公网 URL。

oss.listFiles(sessionId)

列出 session 下所有文件，返回 OssFileInfo[]。

图片压缩

上传图片时自动压缩（浏览器环境，基于 Canvas API），Node.js 环境跳过。

| 配置 | 默认值 | 说明 | |------|--------|------| | enabled | true | 是否启用 | | imageQuality | 0.8 | 质量 0-1 | | imageMaxWidth | 1920 | 最大宽度（px） | | imageMaxHeight | 1080 | 最大高度（px） |

const oss = createOssClient({
  compress: { imageQuality: 0.7, imageMaxWidth: 1280 },
})

文件大小限制

| 类型 | 默认限制 | |------|---------| | 图片（jpg/png/gif/webp/bmp） | 5 MB | | 视频（mp4/webm/mov/avi/mkv/flv/wmv） | 100 MB | | 其他文件 | 10 MB |

const oss = createOssClient({
  limits: { image: 3 * 1024 * 1024, video: 50 * 1024 * 1024 },
})

文件类型校验

• 扩展名白名单：默认允许常见图片、视频、文档、代码文件
• 魔数校验：读取文件头部字节验证真实类型，防止伪造（如 .exe 改名 .jpg）
• 可通过 skipValidation: true 跳过，或自定义白名单：

const oss = createOssClient({
  allowedExtensions: new Set(["jpg", "png", "pdf"]),
})

错误处理

import { OssError, ErrorCode } from "@wecode-team/oss"

try {
  await oss.upload("sid", file, "test.jpg")
} catch (err) {
  if (err instanceof OssError) {
    switch (err.code) {
      case ErrorCode.INVALID_PARAMS: // 参数错误 / 类型校验失败
      case ErrorCode.SESSION_NOT_FOUND: // sessionId 不存在
      case ErrorCode.TIMEOUT: // 请求超时
      case ErrorCode.NETWORK: // 网络错误
      case ErrorCode.SERVER_ERROR: // 服务端错误
    }
  }
}

License

MIT