s3升客户端

MIT License

这是JavaScript运行时间(Deno,Node 22+,Bun,浏览器等)的轻量级S3(对象存储)客户端. 没错设计来提供所有你可能需要的关键特性,而不提供出出血.

主要特点数字 :

有过 无依赖关系 并精密到约21kB( < 8 kB gziped).
- 作为比较,官员 @aws-sdk/client-s3 已经 56个依附区并重399 kB (94 kB gziped) 时间写作的时间.
使用任何S3兼容存储服务的工作: AWS S3, MinIO, Cloudflare R2, Backblaze B2, DigitalOcean Spaces, Supabase存储等.
使用任何支持此程序的 JavaScript 运行时间 fetch API,网络流 API,以及ES模块(ESM). 这个客户端不依赖于任何 NodeJS API 或 Deno API .
在 TypeScript 中被执行并完全输入.
麻省理工学院颁发的许可证(原根据 MiNIO JavaScript 客户端) (中文(简体) ).
2021年起用于生产.

支持的功能

经认证或未经认证的请求
列出对象 : for await (const object of client.listObjects(options)) { ... }
- 透明地处理页标
- 支持使用前缀过滤
- 支助使用分隔符分组 (使用时 client.listObjectsGrouped(...)(中文(简体) )
检查对象是否存在 : client.exists("key")
获取对象的元数据 : client.statObject("key")
- 在请求中可以包含自定义标题 : client.statObject("key", { headers: { 'x-amz-checksum-mode': 'ENABLED' } })
下载对象 : client.getObject("key", options)
- 这仅仅是返回一个标准的 HTTP Response 对象,因此对于大型文件,您可以选择作为流消耗数据 (使用 .body (b) 财产).
下载部分对象 : client.getPartialObject("key", options)
- 喜欢 getObject中,此选项还支持如果想要流出响应.
上传对象 : client.putObject("key", streamOrData, options)
- 可以从一个上传 string, (中文(简体) ), Uint8Array,或 ReadableStream
- 可以将大型上传分为多部分,并平行上传有限的部分.
- 64MB或以上的上传默认会被分成64MB部分. 由于S3最多允许一万个部件,它支持对象可达 640GB; 上传更大的内容, 或流出更大的内容而不经过 size,通过一个更大的 partSize (最高为5GB).
- 可以设置自定义标题,ACL,以及新对象上的其他元数据(下面的例子).
复制对象 : client.copyObject({ sourceKey: "source", options }, "dest", options)
- 可以在不同的桶间复制.
删除对象 : client.deleteObject("key")
创建预先签名的 URL : client.presignedGetObject("key", options) 或者说 client.getPresignedUrl(method, "key", options)
创建预先签名的 POST 策略 : client.presignedPostObject("key", options) 用于直接浏览器上传
检查是否有桶 : client.bucketExists("bucketName")
创建新桶 : client.makeBucket("bucketName")
删除桶 : client.removeBucket("bucketName")

安装

德诺: deno add @bradenmacdonald/s3-lite-client
德诺( 无安装) : import { S3Client } from "jsr:@bradenmacdonald/[email protected]";
国家预防机制: npm add @bradenmacdonald/s3-lite-client
亚伦: yarn add jsr:@bradenmacdonald/s3-lite-client
时间 : pnpm add jsr:@bradenmacdonald/s3-lite-client
宾: bunx jsr add @bradenmacdonald/s3-lite-client

浏览器 :

<script type="module">
import { S3Client } from "https://esm.sh/jsr/@bradenmacdonald/[email protected]";
// Or:
const { S3Client } = await import("https://esm.sh/jsr/@bradenmacdonald/[email protected]");
</script>

用法示例( 快速启动)

从 Amazon S3 上的公共数据集列出数据文件:

import { S3Client } from "@bradenmacdonald/s3-lite-client";

const s3client = new S3Client({
  endPoint: "https://s3.us-east-1.amazonaws.com",
  region: "us-east-1",
  bucket: "openalex",
});

// Log data about each object found under the 'data/concepts/' prefix:
for await (const obj of s3client.listObjects({ prefix: "data/concepts/" })) {
  console.log(obj);
}
// {
//   type: "Object",
//   key: "data/concepts/updated_date=2024-01-25/part_000.gz",
//   etag: "2c9b2843c8d2e9057656e1af1c2a92ad",
//   size: 44105,
//   lastModified: 2024-01-25T22:57:43.000Z
// },
// ...

// Or, to get all the keys (paths) as an array:
const keys = await Array.fromAsync(s3client.listObjects(), (entry) => entry.key);
// keys = [
//  "data/authors/manifest",
//  "data/authors/updated_date=2023-06-08/part_000.gz",
//  ...
// ]

(注:如上所示,列表函数通常向您隐藏页码细节,并将结果转换为单个列表,以检索每个条目。如果您需要请求特定页面,请查看此示例. ) (中文(简体) )

使用本地 S3 兼容服务器( 如 RustFS) 上传并下载文件 :

import { S3Client } from "@bradenmacdonald/s3-lite-client";

// Connecting to a local RustFS server:
const s3client = new S3Client({
  endPoint: "http://localhost:9000",
  region: "dev-region",
  bucket: "dev-bucket",
  accessKey: "AKIA_DEV",
  secretKey: "secretkey",
});

// Upload a file:
await s3client.putObject("test.txt", "This is the contents of the file.");

// Now download it
const result = await s3client.getObject("test.txt");
// and stream the results to a local file:
const localOutFile = await Deno.open("test-out.txt", { write: true, createNew: true });
await result.body!.pipeTo(localOutFile.writable);
// or instead of streaming, you can consume the whole file into memory by awaiting
// result.text(), result.blob(), result.arrayBuffer(), or result.json()

在本地 supabase 开发服务器的 S3 服务上创建一桶 :

const client = new S3Client({
  endPoint: "http://127.0.0.1:54321/storage/v1/s3",
  region: "local",
  accessKey: "paste from output of supabase start",
  secretKey: "paste from output of supabase start",
});
await client.makeBucket("my-bucket");

上传时设置ACLs, Content-Type,自定义元数据等:

await s3client.putObject("key", streamOrData, {
  metadata: {
    "x-amz-acl": "public-read",
    "x-amz-meta-custom": "value",
  },
});

为浏览器直接上传创建预先签名的 POST 策略 :

// Create a presigned POST policy
const { url, fields } = await s3client.presignedPostObject("my-file.txt", {
  expirySeconds: 3600, // URL expires in 1 hour
  fields: {
    "Content-Type": "text/plain",
  },
});

// In the browser, use the policy for direct uploads:
const formData = new FormData();
// Add all required fields from the presigned POST
Object.entries(fields).forEach(([key, value]) => {
  formData.append(key, value);
});
// Add the file content
formData.append("file", fileInput.files[0]);

// Upload the object using the presigned POST
const response = await fetch(url, {
  method: "POST",
  body: formData,
});

if (response.ok) {
  console.log("File uploaded successfully!");
}

更多例子请查看 integration.ts

开发者笔记

为了进行测试,请使用:

deno lint && deno test

要格式化代码,请使用:

deno fmt

要进行整合测试,首先开始 RustFS 红外线使用此命令 :

docker run --rm --name rustfs -e RUSTFS_ACCESS_KEY=AKIA_DEV -e RUSTFS_SECRET_KEY=secretkey -e RUSTFS_REGION=dev-region -e RUSTFS_CONSOLE_ENABLE=true -p 9000:9000 -p 9001:9001 --entrypoint /bin/sh rustfs/rustfs:1.0.4 -c 'mkdir -p /data/dev-bucket && exec /entrypoint.sh rustfs'

当RustFS运行时,运行

deno test --allow-net integration.ts

(如果遇到问题,需要调试 RustFS 所看到的东西, 您可以使用网络控制台浏览水桶 http://localhost:9001/rustfs/console/index.html (中文(简体) ). 并查看服务器的带有此命令的警告/错误日志 :)

docker exec rustfs tail -f /logs/rustfs.log

版本	发布日期	距今
`1.0.1`latest	2026/10/30	9 天前
`1.0.0`	2026/08/14	2 个月前
`0.9.6`	2026/03/30	7 个月前
`0.9.5`	2026/03/30	7 个月前

@bradenmacdonald/s3-lite-client

s3升客户端

支持的功能

安装

用法示例( 快速启动)

开发者笔记

版本与发布记录

关于 @bradenmacdonald/s3-lite-client 的常见问题

@bradenmacdonald/s3-lite-client 是什么？

如何安装 @bradenmacdonald/s3-lite-client？

@bradenmacdonald/s3-lite-client 支持 TypeScript 吗？

@bradenmacdonald/s3-lite-client 支持 ESM 还是 CommonJS？

@bradenmacdonald/s3-lite-client 可以商用吗？

@bradenmacdonald/s3-lite-client 的下载量有多少？

@bradenmacdonald/s3-lite-client 还在维护吗？