fast-s3-presigner

极致性能、零依赖、用于 Node.js 的 S3 预签名 URL 生成器。

English | [简体中文]

特性

• 极致性能 - 专为高吞吐量和高并发环境优化。
• 零依赖 - 仅使用 Node.js 内置的 crypto 模块。
• 极小体积 - 约 7KB。
• 同步 API - 无异步开销。
• 双模支持 (ESM/CJS) - 随处可用。
• TypeScript - 完整的类型安全支持。
• S3 POST 上传 - 支持浏览器端表单上传。

要求

Node.js >= 20.12.0 (由于使用了 crypto.hash() 一次性哈希接口)

安装

npm install fast-s3-presigner

性能测试

测试环境：AMD Ryzen 7 5700G, Node.js v24.14.1 (原始操作延迟，3 次平均值):

| 库 | GET (简单 Key) | GET (复杂 Key) | PUT | POST | 1000 次顺序 GET | |---------|------------------|-------------------|-----|------|---------------------| | fast-s3-presigner | 4.11 µs | 4.80 µs | 3.93 µs | 3.64 µs | 3.92 ms | | lean-s3 | 10.94 µs (2.7x) | 11.78 µs (2.5x) | 10.41 µs (2.6x) | 9.54 µs (2.6x) | 10.21 ms (2.6x) | | aws4 | 18.68 µs (4.5x) | 19.64 µs (4.1x) | 16.36 µs (4.2x) | - | 16.16 ms (4.1x) | | s3mini | 97.69 µs (23.8x) | 99.31 µs (20.7x) | 94.31 µs (24.0x) | - | 95.38 ms (24.3x) | | AWS SDK (v3) | 292.50 µs (71.2x) | 277.36 µs (57.8x) | 291.25 µs (74.1x) | 51.30 µs (14.1x) | 239.91 ms (61.2x) | | aws4fetch | 319.82 µs (77.8x) | 285.37 µs (59.5x) | 275.18 µs (70.0x) | - | 269.92 ms (68.9x) |

注："-" 表示该库不支持 POST 预签名 URL。

快速开始

import { S3Presigner } from "fast-s3-presigner";

const presigner = new S3Presigner({
  endpoint: "https://s3.us-east-1.amazonaws.com",
  region: "us-east-1",
  bucket: "my-bucket",
  accessKeyId: "AKIAIOSFODNN7EXAMPLE",
  secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
});

// 生成下载 URL (GET, 1 小时过期)
const downloadUrl = presigner.presign("photos/image.jpg");

// 生成上传 URL (PUT, 带 Content-Type)
const uploadUrl = presigner.presign("uploads/file.txt", {
  method: "PUT",
  contentType: "text/plain",
  expiresIn: 3600,
});

// 为浏览器表单提交生成 POST 上传策略
const postOptions = presigner.presignPost("uploads/video.mp4", {
  expiresIn: 3600,
  conditions: [
    ["content-length-range", 0, 10485760] // 最大 10MB
  ]
});
// <form action={postOptions.url} method="POST" enctype="multipart/form-data">
// 插入来自 postOptions.fields 的隐藏表单项

API

new S3Presigner(config)

| 选项 | 类型 | 必填 | 描述 | |--------|------|----------|-------------| | endpoint | string | 是 | S3 服务端点 URL (例如 https://s3.us-east-1.amazonaws.com)。虚拟托管风格下 bucket 名称会自动拼接到域名前。 | | region | string | 是 | AWS 区域 | | bucket | string | 是 | 存储桶名称 | | accessKeyId | string | 是 | AWS Access Key ID | | secretAccessKey | string | 是 | AWS Secret Access Key | | sessionToken | string | 否 | 临时凭证的 Session Token | | forcePathStyle | boolean | 否 | 强制使用路径风格 URL (localhost/IP 会自动检测) |

presigner.presign(key, options?)

为 GET/PUT/HEAD/DELETE 请求返回预签名 URL 字符串。

| 选项 | 类型 | 默认值 | 描述 | |--------|------|---------|-------------| | method | "GET" \| "PUT" \| "DELETE" \| "HEAD" | "GET" | HTTP 方法 | | expiresIn | number | 3600 | 过期时间（秒，范围 1 - 604800） | | contentType | string | - | 需要签名的 Content-Type 标头 | | contentLength | number | - | 需要签名的 Content-Length 标头 | | acl | string | - | S3 ACL (例如 "public-read") | | storageClass | string | - | 存储类型 (例如 "GLACIER") | | responseContentDisposition | string | - | 响应 Content-Disposition 覆盖 | | responseContentType | string | - | 响应 Content-Type 覆盖 | | additionalSignedHeaders | Record<string, string> | - | 其他需要签名的标头 |

presigner.presignPost(key, options?)

返回一个 PresignPostResult，包含浏览器表单 POST 上传所需的 url 和 fields。

| 选项 | 类型 | 默认值 | 描述 | |--------|------|---------|-------------| | expiresIn | number | 3600 | 过期时间（秒，范围 1 - 604800） | | conditions | Array | - | 额外的 POST 策略条件 | | fields | Record<string, string> | - | 额外的表单字段（严格签名） |

端点示例

// AWS S3 (虚拟托管风格)
endpoint: "https://s3.us-east-1.amazonaws.com"
// bucket 会自动拼接: https://my-bucket.s3.us-east-1.amazonaws.com

// AWS S3 (路径风格)
endpoint: "https://s3.us-east-1.amazonaws.com"
// + forcePathStyle: true

// MinIO / LocalStack
endpoint: "http://localhost:9000"
// localhost/IP 会自动检测为路径风格

// Cloudflare R2
endpoint: "https://<account-id>.r2.cloudflarestorage.com"
// bucket 会自动拼接: https://my-bucket.<account-id>.r2.cloudflarestorage.com

// 自定义 S3 兼容端点
endpoint: "https://s3.example.com"

许可证

ISC