@taoya7/s3-storage

S3/OSS 存储抽象库，支持 AWS S3、阿里云 OSS 以及其他兼容 S3 协议的对象存储服务。

特性

• 🚀 支持 AWS S3、阿里云 OSS 等 S3 兼容服务
• 📦 支持文件上传、下载、删除、移动等操作
• 🔐 支持预签名 URL 和预签名 POST
• 🌐 支持 CDN 加速域名配置
• 📝 完整的 TypeScript 类型支持
• 🔧 可配置的日志记录器

快速开始

基本用法

import { S3Storage } from '@taoya7/s3-storage'
import type { S3StorageConfig } from '@taoya7/s3-storage'

// 配置存储
const config: S3StorageConfig = {
  AWS_ACCESS_KEY_ID: 'your-access-key',
  AWS_SECRET_ACCESS_KEY: 'your-secret-key',
  AWS_REGION: 'us-east-1',
  AWS_S3_UPLOAD_BUCKET_NAME: 'your-bucket-name',
  AWS_S3_UPLOAD_BUCKET_URL: 'https://s3.amazonaws.com',
}

// 创建存储实例
const storage = new S3Storage(config)

// 上传文件
const fileUrl = await storage.store({
  key: 'path/to/file.jpg',
  body: fileBuffer,
  contentType: 'image/jpeg',
  acl: 'public-read',
})

console.log('文件已上传:', fileUrl)

使用 CDN 加速

const config: S3StorageConfig = {
  AWS_ACCESS_KEY_ID: 'your-access-key',
  AWS_SECRET_ACCESS_KEY: 'your-secret-key',
  AWS_REGION: 'us-east-1',
  AWS_S3_UPLOAD_BUCKET_NAME: 'your-bucket-name',
  AWS_S3_UPLOAD_BUCKET_URL: 'https://s3.amazonaws.com',
  // 配置 CDN 加速域名
  AWS_S3_ACCELERATE_URL: 'https://cdn.example.com',
}

const storage = new S3Storage(config)

使用阿里云 OSS

const config: S3StorageConfig = {
  AWS_ACCESS_KEY_ID: 'your-aliyun-access-key',
  AWS_SECRET_ACCESS_KEY: 'your-aliyun-secret-key',
  AWS_REGION: 'oss-cn-hangzhou',
  AWS_S3_UPLOAD_BUCKET_NAME: 'your-bucket-name',
  AWS_S3_UPLOAD_BUCKET_URL: 'https://your-bucket-name.oss-cn-hangzhou.aliyuncs.com',
  AWS_S3_FORCE_PATH_STYLE: false,
}

const storage = new S3Storage(config)

自定义日志记录器

import { S3Storage, createConsoleLogger } from '@taoya7/s3-storage'
import type { Logger } from '@taoya7/s3-storage'

// 使用默认的控制台日志
const storage1 = new S3Storage(config, createConsoleLogger())

// 使用自定义日志记录器
const customLogger: Logger = {
  info: (message, meta) => {
    // 自定义 info 日志处理
  },
  warn: (message, meta) => {
    // 自定义 warn 日志处理
  },
  error: (message, meta) => {
    // 自定义 error 日志处理
  },
}

const storage2 = new S3Storage(config, customLogger)

API 文档

S3Storage

构造函数

constructor(config: S3StorageConfig, logger?: Logger)

方法

store()

上传文件到存储服务。

await storage.store({
  key: 'path/to/file.jpg',
  body: Buffer.from('file content'),
  contentType: 'image/jpeg',
  acl: 'public-read', // 可选: 'private' | 'public-read' | 'public-read-write' 等
})

createUpload()

创建文件上传凭证，封装了预签名 POST 和文件元信息，适合前端直传场景。

const { uploadUrl, form, attachment } = await storage.createUpload({
  filename: 'photo.jpg',
  contentType: 'image/jpeg',
  size: 1347965, // 文件大小（字节）
})

// uploadUrl  - 上传端点
// form       - 预签名表单字段，直接拼入 FormData
// attachment - 文件元信息 { contentType, filename, path, size, url }

前端使用示例：

const formData = new FormData()
Object.entries(form).forEach(([key, value]) => formData.append(key, value))
formData.append('file', file)

await fetch(uploadUrl, { method: 'POST', body: formData })

// 上传完成后，通过 attachment.url 访问文件
console.log('文件地址:', attachment.url)

getPresignedPost()

生成预签名的 POST 上传凭证，用于客户端直接上传。

const presignedPost = await storage.getPresignedPost(
  'path/to/file.jpg',
  10485760, // 最大上传大小（字节）
  'image/jpeg'
)

getSignedUrl()

生成签名 URL 用于私有文件访问。

const signedUrl = await storage.getSignedUrl(
  'path/to/file.jpg',
  3600, // 过期时间（秒）
  'download-filename.jpg' // 可选：下载文件名
)

getFileStream()

获取文件的可读流。

const stream = await storage.getFileStream('path/to/file.jpg')

getFile()

获取完整的文件内容为 Buffer。

const buffer = await storage.getFile('path/to/file.jpg')

deleteFile()

删除单个文件。

await storage.deleteFile('path/to/file.jpg')

deleteDirectory()

删除目录（删除指定前缀的所有文件）。

await storage.deleteDirectory('path/to/directory/')

moveFile()

移动（重命名）文件。

await storage.moveFile('old/path/file.jpg', 'new/path/file.jpg')

moveDirectory()

移动整个目录。

await storage.moveDirectory('old/path/', 'new/path/')

listFiles()

列出指定前缀的文件。

const result = await storage.listFiles('path/prefix/', 100)
console.log(result.files)
console.log(result.isTruncated)
console.log(result.nextContinuationToken)

setObjectAcl()

设置对象的访问控制列表 (ACL)。

await storage.setObjectAcl('path/to/file.jpg', 'public-read')

配置选项

S3StorageConfig

interface S3StorageConfig {
  /** AWS/OSS 访问密钥 ID */
  AWS_ACCESS_KEY_ID: string
  /** AWS/OSS 访问密钥 */
  AWS_SECRET_ACCESS_KEY: string
  /** AWS 区域 */
  AWS_REGION: string
  /** S3/OSS 上传桶名称 */
  AWS_S3_UPLOAD_BUCKET_NAME: string
  /** S3/OSS 上传桶 URL（可选） */
  AWS_S3_UPLOAD_BUCKET_URL?: string
  /** S3/OSS 加速 URL（CDN 域名，可选） */
  AWS_S3_ACCELERATE_URL?: string
  /** 是否强制使用路径风格（可选） */
  AWS_S3_FORCE_PATH_STYLE?: boolean
  /** 默认 ACL 权限（可选） */
  AWS_S3_ACL?: string
}

环境变量配置

本项目支持使用环境变量进行配置，便于开发和测试。

快速开始

# 1. 复制示例配置文件
cp .env.example .env

# 2. 编辑 .env 文件，填入你的配置
# AWS_ACCESS_KEY_ID=your-access-key
# AWS_SECRET_ACCESS_KEY=your-secret-key
# ...