@ismartify/oss

@ismartify/oss

轻量级的阿里云 OSS SDK，支持 V2 签名、自定义 Endpoint 和 Unstorage Driver。

特性

• ✅ 支持阿里云 OSS V2 签名
• ✅ 完整的 CRUD 操作（上传、下载、删除、列表）
• ✅ JSON 数据的便捷操作
• ✅ 自定义 Endpoint 支持（CDN、内网等）
• ✅ Unstorage Driver 集成
• ✅ TypeScript 类型定义
• ✅ 零依赖（除必需的底层库）

安装

npm install @ismartify/oss

快速开始

基础用法

import { OSSClient } from '@ismartify/oss';

const client = new OSSClient({
  region: 'oss-cn-shenzhen',
  accessKeyId: 'YOUR_ACCESS_KEY_ID',
  accessKeySecret: 'YOUR_ACCESS_KEY_SECRET',
  bucket: 'your-bucket',
  headerEncoding: 'utf-8'
});

// 上传文件
await client.put('path/to/file.txt', 'Hello World');

// 下载文件
const result = await client.get('path/to/file.txt');
console.log(result.content.toString());

// 删除文件
await client.delete('path/to/file.txt');

// 列出文件
const list = await client.list({ prefix: 'path/', maxKeys: 10 });
console.log(list.objects);

使用自定义 Endpoint

const client = new OSSClient({
  region: 'oss-cn-shenzhen',
  accessKeyId: 'YOUR_ACCESS_KEY_ID',
  accessKeySecret: 'YOUR_ACCESS_KEY_SECRET',
  bucket: 'your-bucket',
  endpoint: 'https://cdn.example.com'  // 自定义域名
});

// 现在所有操作都会通过自定义域名访问

JSON 数据操作

// 上传 JSON
await client.putJSON('data/config.json', {
  theme: 'dark',
  language: 'zh-CN'
});

// 下载 JSON
const data = await client.getJSON('data/config.json');
console.log(data.data); // { theme: 'dark', language: 'zh-CN' }

生成签名 URL

// GET 签名 URL（1小时有效期）
const url = await client.sign('path/to/file.txt');

// PUT 签名 URL（用于上传）
const uploadUrl = await client.sign('path/to/file.txt', {
  method: 'PUT',
  expires: 1800,
  contentType: 'application/json'
});

// 带响应头控制的签名 URL
const downloadUrl = await client.sign('path/to/file.txt', {
  expires: 3600,
  response: {
    'content-type': 'application/json',
    'content-disposition': 'attachment; filename="download.json"'
  }
});

Unstorage 集成

与 Unstorage 无缝集成，将 OSS 作为存储后端。

import { createStorage } from 'unstorage';
import { OSSClient, createOSSDriver } from '@ismartify/oss';

const client = new OSSClient({
  region: 'oss-cn-shenzhen',
  accessKeyId: 'YOUR_ACCESS_KEY_ID',
  accessKeySecret: 'YOUR_ACCESS_KEY_SECRET',
  bucket: 'your-bucket'
});

const storage = createStorage({
  driver: createOSSDriver(client)({
    base: 'storage',
    prefix: 'app'
  })
});

// 使用 Unstorage API
await storage.setItem('user:123', { name: '张三', age: 30 });
const user = await storage.getItem('user:123');
await storage.removeItem('user:123');
const keys = await storage.getKeys();

API 文档

OSSClient

构造函数

new OSSClient(options: OSSClientOptions)

OSSClientOptions:

参数	类型	必填	说明
region	string	否	OSS 区域，默认 'cn-hangzhou'
accessKeyId	string	是	阿里云 AccessKey ID
accessKeySecret	string	是	阿里云 AccessKey Secret
bucket	string	是	OSS Bucket 名称
headerEncoding	string	否	头部编码，默认 'utf-8'
timeout	number	否	请求超时时间
endpoint	string	否	自定义 Endpoint

方法

put(objectName, data, options?)

上传对象到 OSS。

await client.put(objectName: string, data: string | Buffer, options?: {
  contentType?: string;
  contentMd5?: string;
  meta?: Record<string, string>;
}): Promise<PutResult>

get(objectName, options?)

从 OSS 下载对象。

await client.get(objectName: string, options?: {
  range?: string;
}): Promise<GetResult>

delete(objectName)

删除 OSS 对象。

await client.delete(objectName: string): Promise<DeleteResult>

head(objectName)

获取对象元数据。

await client.head(objectName: string): Promise<HeadResult>

list(options?)

列出 OSS 对象。

await client.list(options?: {
  prefix?: string;
  maxKeys?: number;
  continuationToken?: string;
  delimiter?: string;
}): Promise<ListResult>

putJSON(objectName, data, options?)

上传 JSON 对象。

await client.putJSON<T>(objectName: string, data: T, options?: {
  meta?: Record<string, string>;
}): Promise<PutJSONResult>

getJSON(objectName, options?)

下载并解析 JSON 对象。

await client.getJSON<T>(objectName: string, options?: {
  range?: string;
}): Promise<GetJSONResult<T>>

sign(objectName, options?)

生成签名 URL。

await client.sign(objectName: string, options?: {
  method?: string;
  expires?: number;
  contentType?: string;
  response?: Record<string, string>;
}): Promise<string>

Unstorage Driver API

createOSSDriver(client)

创建 Unstorage Driver。

import { createOSSDriver } from '@ismartify/oss';

const driver = createOSSDriver(client)({
  base: 'storage',    // 基础路径
  prefix: 'app'       // 前缀
});

支持的 Unstorage 方法:

• ✅ setItem(key, value) - 设置值
• ✅ getItem(key) - 获取值
• ✅ hasItem(key) - 检查是否存在
• ✅ removeItem(key) - 删除
• ✅ getKeys(base?) - 获取键列表
• ✅ clear(base?) - 清空
• ⚠️ watch(callback) - 不支持（返回空函数）

使用场景

1. 文件存储

// 上传用户头像
await client.put('avatars/user-123.jpg', imageBuffer, {
  contentType: 'image/jpeg',
  meta: { userId: '123' }
});

// 下载文件
const avatar = await client.get('avatars/user-123.jpg');

2. 配置管理

// 使用 Unstorage
const config = createStorage({
  driver: createOSSDriver(client)({
    base: 'config'
  })
});

await config.setItem('app', { theme: 'dark', lang: 'zh' });
const settings = await config.getItem('app');

3. CDN 加速

const client = new OSSClient({
  region: 'oss-cn-shenzhen',
  accessKeyId: 'YOUR_KEY',
  accessKeySecret: 'YOUR_SECRET',
  bucket: 'your-bucket',
  endpoint: 'https://cdn.example.com'
});

4. 数据缓存

const cache = createStorage({
  driver: createOSSDriver(client)({
    base: 'cache',
    prefix: 'api'
  })
});

await cache.setItem('users/123', userData);
const cached = await cache.getItem('users/123');

示例

查看 demo/ 目录获取更多示例：

• demo/simple-test.js - 基础功能测试
• demo/sign.js - 签名 URL 生成
• demo/custom-endpoint-demo.js - 自定义 Endpoint
• demo/unstorage-demo.js - Unstorage 集成

运行示例：

node demo/simple-test.js
node demo/sign.js
node demo/unstorage-demo.js

文档

• 自定义 Endpoint 使用指南
• Unstorage Driver 使用指南

注意事项

• 签名版本: 使用阿里云 OSS V2 签名算法
• Content-Length: 自动计算正确的字节长度（支持多字节字符）
• 自定义域名: 需要在阿里云 OSS 控制台绑定域名
• 并发控制: 大量操作时建议使用 Promise 并发控制
• 错误处理: 所有方法都会抛出异常，请使用 try-catch

开发

# 安装依赖
npm install

# 运行测试
npm test

# 构建
npm run build

# 发布
npm run npm:publish

许可证

ISC

贡献

欢迎提交 Issue 和 Pull Request！

相关链接

• 阿里云 OSS 文档
• Unstorage