s3mini

在开始之前，您必须生成 Access Key。所有示例都将使用 access_key_id 和 access_key_secret 变量，分别代表您生成的 Access Key ID（访问密钥 ID） 和 Secret Access Key（秘密访问密钥） 值。

s3mini ↗ 是一个零依赖、轻量级（压缩后约 20 KB）的 TypeScript S3 客户端，使用 AWS SigV4 签名。它可在 Node.js、Bun 和 Cloudflare Workers 上原生运行，无需 polyfill。

与 AWS SDK 不同，s3mini 期望使用存储桶作用域的端点——存储桶名称是端点 URL 的一部分，因此您无需为每个操作单独传入 bucket 参数。

安装

npm install s3mini

Node.js / Bun

import { S3mini } from "s3mini";

const s3 = new S3mini({
	accessKeyId: process.env.R2_ACCESS_KEY_ID!,
	secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
	// Bucket-scoped endpoint — include your bucket name in the path
	endpoint: `https://${process.env.ACCOUNT_ID}.r2.cloudflarestorage.com/my-bucket`,
	region: "auto",
});

// Upload an object
await s3.putObject("hello.txt", "Hello from s3mini!");

// Download an object as a string
const text = await s3.getObject("hello.txt");
console.log(text);

// List objects with a prefix
const objects = await s3.listObjects("/", "hello");
console.log(objects);

// Delete an object
await s3.deleteObject("hello.txt");

Cloudflare Workers

s3mini 可在 Workers 中原生运行，无需 nodejs_compat 兼容性标志。

import { S3mini } from "s3mini";

interface Env {
	R2_ACCESS_KEY_ID: string;
	R2_SECRET_ACCESS_KEY: string;
	ACCOUNT_ID: string;
}

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const s3 = new S3mini({
			accessKeyId: env.R2_ACCESS_KEY_ID,
			secretAccessKey: env.R2_SECRET_ACCESS_KEY,
			endpoint: `https://${env.ACCOUNT_ID}.r2.cloudflarestorage.com/my-bucket`,
			region: "auto",
		});

		const url = new URL(request.url);
		const key = url.pathname.slice(1); // strip leading "/"

		if (!key) {
			return new Response("Missing object key", { status: 400 });
		}

		switch (request.method) {
			case "PUT": {
				const data = await request.arrayBuffer();
				const contentType =
					request.headers.get("content-type") ?? "application/octet-stream";
				await s3.putObject(key, new Uint8Array(data), contentType);
				return new Response("Created", { status: 201 });
			}

			case "GET": {
				const response = await s3.getObjectResponse(key);
				if (!response) {
					return new Response("Not Found", { status: 404 });
				}
				return new Response(response.body, {
					headers: {
						"content-type":
							response.headers.get("content-type") ??
							"application/octet-stream",
						etag: response.headers.get("etag") ?? "",
					},
				});
			}

			case "DELETE": {
				await s3.deleteObject(key);
				return new Response(null, { status: 204 });
			}

			default:
				return new Response("Method Not Allowed", { status: 405 });
		}
	},
};