# @bradenmacdonald/s3-lite-client 中文文档 规范地址：https://npmcn.com/package/%40bradenmacdonald/s3-lite-client/ 版本：1\.0\.1 npm 元数据更新时间：2026-10-30T03:47:29.274Z 中文译文更新时间：2026-11-08T13:21:04.635Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40bradenmacdonald/s3-lite-client 原文对照：https://npmcn.com/package/%40bradenmacdonald/s3-lite-client/?lang=original 项目主页：https://jsr.io/@bradenmacdonald/s3-lite-client 源码仓库：https://github.com/bradenmacdonald/s3-lite-client ## 关键信息（来自 npm 元数据） - 包体积（解压后）：309 kB，51 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：0 个 - 首次发布：2026-03-29T17:31:04.677Z - 最新版本发布：2026-10-30T03:47:28.988Z - 近 30 天下载量：12880（2026-10-09 至 2026-11-07，npm 官方下载统计） - 已发布版本数：4（近 12 个月 4 个） ## 中文简介 轻量级S3客户端. ## 安装 ```sh npm install @bradenmacdonald/s3-lite-client ``` 也可以使用：`pnpm add @bradenmacdonald/s3-lite-client`、`yarn add @bradenmacdonald/s3-lite-client`、`bun add @bradenmacdonald/s3-lite-client` ## README # s3升客户端 ![MIT License](https://img.shields.io/npm/l/%40bradenmacdonald%2Fs3-lite-client) [![no dependencies](https://depx.co/api/badge/@bradenmacdonald/s3-lite-client)](https://depx.co/pkg/@bradenmacdonald/s3-lite-client) [![minimized gzipped size](https://img.shields.io/bundlejs/size/%40bradenmacdonald%2Fs3-lite-client)](https://bundlejs.com/?q=%40bradenmacdonald%2Fs3-lite-client&treeshake=%5B*%5D&text=%22const+s3client+%3D+new+S3Client%28%7B%5Cn++endPoint%3A+%5C%22https%3A%2F%2Fs3.us-east-1.amazonaws.com%5C%22%2C%5Cn++region%3A+%5C%22us-east-1%5C%22%2C%5Cn++bucket%3A+%5C%22openalex%5C%22%2C%5Cn%7D%29%3B%5Cn%5Cn%2F%2F+Log+data+about+each+object+found+under+the+%27data%2Fconcepts%2F%27+prefix%3A%5Cnfor+await+%28const+obj+of+s3client.listObjects%28%7B+prefix%3A+%5C%22data%2Fconcepts%2F%5C%22+%7D%29%29+%7B%5Cn++console.log%28obj%29%3B%5Cn%7D%22) [![JSR Version](https://jsr.io/badges/@bradenmacdonald/s3-lite-client)](https://jsr.io/@bradenmacdonald/s3-lite-client) [![NPM Version](https://img.shields.io/npm/v/%40bradenmacdonald%2Fs3-lite-client)](https://www.npmjs.com/package/@bradenmacdonald/s3-lite-client) [![JSR Downloads](https://jsr.io/badges/@bradenmacdonald/s3-lite-client/total-downloads)](https://jsr.io/@bradenmacdonald/s3-lite-client) 这是JavaScript运行时间(Deno,Node 22+,Bun,浏览器等)的轻量级S3(对象存储)客户端. 没错 设计来提供所有你可能需要的关键特性,而不提供出出血. **主要特点**数字 : - 有过 **无依赖关系** 并精密到约21kB( < 8 kB gziped). - 作为比较,官员 `@aws-sdk/client-s3` 已经 [56个依附区并重399 kB (94 kB gziped)](https://bundlephobia.com/package/@aws-sdk/client-s3@3.758.0) 时间 写作的时间. - 使用任何S3兼容存储服务的工作: AWS S3, MinIO, Cloudflare R2, Backblaze B2, DigitalOcean Spaces, Supabase存储等. - 使用任何支持此程序的 JavaScript 运行时间 `fetch` API,网络流 API,以及ES模块(ESM). 这个客户端 不依赖于任何 NodeJS API 或 Deno API . - 在 TypeScript 中被执行并完全输入. - 麻省理工学院颁发的许可证(原根据 [MiNIO JavaScript 客户端](https://github.com/minio/minio-js)) (中文(简体) ). - 2021年起用于生产. ## 支持的功能 - 经认证或未经认证的请求 - 列出对象 : `for await (const object of client.listObjects(options)) { ... }` - 透明地处理页标 - 支持使用前缀过滤 - 支助 [使用分隔符分组](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-prefixes.html) (使用时 `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/s3-lite-client@1.0.1";` - 国家预防机制: `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` - 浏览器 : ```html ``` ## 用法示例( 快速启动) **从 Amazon S3 上的公共数据集列出数据文件:** ```typescript 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", // ... // ] ``` _(注:如上所示,列表函数通常向您隐藏页码细节,并将结果转换为单个 列表,以检索每个条目。 如果您需要请求特定页面,请查看 [此示例](https://github.com/bradenmacdonald/s3-lite-client/blob/7cd52c07a78cdefc8d890dc5b5dc95f65ea20bc5/integration.ts#L520-L573). ) (中文(简体) )_ **使用本地 S3 兼容服务器( 如 RustFS) 上传并下载文件 :** ```typescript 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 服务上创建一桶 :** ```ts 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,自定义元数据等:** ```ts await s3client.putObject("key", streamOrData, { metadata: { "x-amz-acl": "public-read", "x-amz-meta-custom": "value", }, }); ``` **为浏览器直接上传创建预先签名的 POST 策略 :** ```ts // 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`](https://npmcn.com/package/%40bradenmacdonald/s3-lite-client/integration.ts) ## 开发者笔记 为了进行测试,请使用: ```sh deno lint && deno test ``` 要格式化代码,请使用: ```sh deno fmt ``` 要进行整合测试,首先开始 [RustFS 红外线](https://rustfs.com/) 使用此命令 : ```sh 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运行时,运行 ```sh deno test --allow-net integration.ts ``` (如果遇到问题,需要调试 RustFS 所看到的东西, 您可以使用网络控制台浏览水桶 http://localhost:9001/rustfs/console/index.html (中文(简体) ). 并查看服务器的 带有此命令的警告/错误日志 :) ```sh docker exec rustfs tail -f /logs/rustfs.log ``` ## 常见问题 ### @bradenmacdonald/s3-lite-client 是什么？ 轻量级S3客户端\. ### 如何安装 @bradenmacdonald/s3-lite-client？ 在项目目录运行 npm install @bradenmacdonald/s3-lite-client，或使用 pnpm add / yarn add / bun add。 ### @bradenmacdonald/s3-lite-client 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @bradenmacdonald/s3-lite-client 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @bradenmacdonald/s3-lite-client 可以商用吗？ @bradenmacdonald/s3-lite-client 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @bradenmacdonald/s3-lite-client 的下载量有多少？ 根据 npm 官方下载统计，@bradenmacdonald/s3-lite-client 在 2026/10/09 – 2026/11/07 这 30 天内被下载 12,880 次，日均约 429 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @bradenmacdonald/s3-lite-client 还在维护吗？ 最新版本 1\.0\.1 发布于 2026/10/30（9 天前）；至今共发布 4 个版本，其中过去 12 个月发布了 4 个；首次发布于 2026/03/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。