fluffy-oss-sdk

Fluffy OSS 文件上传客户端 SDK，支持签名认证、上传进度，以及可选的 UniApp/App-Plus 原生上传适配器。

安装

npm install fluffy-oss-sdk@^0.2.1

如果需要在 Node.js 中获取上传进度，请额外安装可选的 Axios 依赖：

npm install axios

快速开始

import { FluffyOssClient } from 'fluffy-oss-sdk'

const client = new FluffyOssClient({
  baseUrl: 'https://your-backend.example/api',
  appId: 'your-app-id',
  secret: 'your-app-secret',
})

const result = await client.upload(file, {
  applicationId: '1',
  onProgress: ({ percent }) => console.log(`${percent}%`),
})

支持的上传输入

| 运行环境 | 输入类型 | 上传方式 | | --- | --- | --- | | 浏览器 | File | 需要进度时使用 XMLHttpRequest，否则使用 fetch | | Node.js | Buffer、Uint8Array 或本地文件路径 | 使用 fetch；Axios 可提供上传进度 | | UniApp App-Plus | 非空的本地临时文件路径字符串 | adapterUni: true 时使用 uni.uploadFile |

完整的 UniApp/App-Plus 调用方接入说明（包括选择器数据处理和取消上传 UI）请参阅 App-Plus 集成指南。

UniApp/App-Plus

仅在真正的 App-Plus 构建中启用 adapterUni，并将选择器返回的本地文件路径原样传入：

const client = new FluffyOssClient({
  baseUrl: 'https://your-backend.example/api',
  appId: 'your-app-id',
  secret: 'your-app-secret',
  adapterUni: true,
})

const result = await client.upload(tempFilePath, {
  applicationId: '1',
  timeout: 60_000,
  onProgress: ({ percent }) => console.log(`${percent}%`),
})

UniApp 适配器会拒绝非字符串或空白路径，并且不会回退到浏览器或 Node.js 上传方式。原生上传会提交 file、applicationId 和可选的 callbackUrl 字段；filename 和 mime 参数在原生上传中会被忽略。原生进度可以提供 percent，但由于 UniApp 无法稳定提供字节数，loaded 和 total 会报告为 0。

App-Plus 必须提供安全的 Web Crypto 能力（crypto.subtle 和安全随机数生成能力）用于请求签名。在浏览器和 UniApp 运行环境中，SDK 不使用 Node.js crypto、plus.crypto 或不安全的 JavaScript 降级方案。

上传选项

| 选项 | 类型 | 说明 | | --- | --- | --- | | applicationId | string | 目标应用 ID。为保持兼容性，默认值为 "1"。 | | callbackUrl | string | 随上传请求发送的可选回调地址。 | | filename | string | Node.js 上传时使用的自定义文件名。在 UniApp 中会被忽略。 | | mime | string | Node.js 上传时使用的自定义 MIME 类型。在 UniApp 中会被忽略。 | | onProgress | (progress: UploadProgress) => void | 上传进度回调。 | | timeout | number | 上传超时时间，单位为毫秒，必须为正数。 | | signal | AbortSignal | 当信号被中止时取消上传。 |

SDK 不会自动重试上传，因为重试 multipart 请求可能导致服务端创建重复的上传任务。

错误处理

import {
  ApiError,
  NetworkError,
  UploadCanceledError,
  UploadTimeoutError,
} from 'fluffy-oss-sdk'

try {
  await client.upload(file, { applicationId: '1', timeout: 60_000 })
} catch (error) {
  if (error instanceof UploadTimeoutError) {
    console.error('上传超过了设定的时间限制')
  } else if (error instanceof UploadCanceledError) {
    console.error('上传已取消')
  } else if (error instanceof ApiError) {
    console.error(error.status, error.message)
  } else if (error instanceof NetworkError) {
    console.error(error.message)
  }
}

• ApiError：已收到服务端响应，但 HTTP 状态码、API 响应信封或响应数据不符合成功条件。
• NetworkError：未收到可用响应，包括原生 uni.uploadFile 失败。
• UploadTimeoutError：上传超过了配置的超时时间。
• UploadCanceledError：调用方提供的 AbortSignal 被中止。

当 Node.js 环境中可以解析到 Axios 时，SDK 仅使用 Axios 提供上传进度。如果无法解析 Axios，Node.js 会回退到不带进度的 fetch。已经开始执行的 Axios 请求失败后，不会再次通过 fetch 重试。

开发命令

npm run typecheck
npm test
npm run build
npm pack --dry-run