S3

s3 模块是一个基于 AWS SDK for Go v2 封装的原生 Amazon S3 协议插件。

它既可以直接访问 Amazon S3，也可以访问兼容 S3 协议的对象存储服务。和 rustfs 不同的是，s3 更贴近原生 S3 API，适合需要完整 Bucket / Object / Multipart / Presign 能力的场景。

安装和使用

import s3 from "s3";

const client = s3.open({
    region: "us-east-1",
    accessKey: "YOUR_ACCESS_KEY",
    secretKey: "YOUR_SECRET_KEY",
});

如果需要连接兼容 S3 协议的对象存储，也可以指定 endpoint：

import s3 from "s3";

const client = s3.open({
    endpoint: "http://127.0.0.1:9000",
    region: "us-east-1",
    accessKey: "minioadmin",
    secretKey: "minioadmin",
    usePathStyle: true,
});

S3 的 API

名称	类型	参数	返回值	说明
open	方法	`config:object`	Client	创建一个 S3 客户端

open

创建一个新的 S3 客户端实例。

参数

config: 配置对象
- region: AWS 区域，默认 us-east-1
- accessKey: Access Key，可选；如果不传，会走默认凭证链
- secretKey: Secret Key，可选
- sessionToken: 临时凭证的 SessionToken，可选
- endpoint: 自定义 S3 Endpoint，可选
- usePathStyle: 是否启用 Path Style，可选，默认 false
- useAccelerate: 是否启用 S3 Accelerate，可选
- useDualstack: 是否启用 DualStack，可选

示例

import s3 from "s3";

const client = s3.open({
    region: "ap-southeast-1",
    accessKey: "YOUR_ACCESS_KEY",
    secretKey: "YOUR_SECRET_KEY",
});

参数约定

s3 模块中的大多数客户端方法都接收一个对象参数，并且字段名尽量与 AWS SDK v2 对应的 Input 结构保持一致。

例如：

client.headObject({
    Bucket: "demo-bucket",
    Key: "hello.txt",
});

也支持使用更符合脚本习惯的大小写写法，例如：

client.headObject({
    bucket: "demo-bucket",
    key: "hello.txt",
});

特殊参数

以下几个参数是文档里需要特别注意的：

body 用于 putObject、uploadPart 这类上传接口，支持 string、buffer、reader
filePath 也可用于 putObject、uploadPart，直接从本地文件读取内容上传
savePath 可用于 getObject，将下载内容额外保存到本地文件
expiresIn 用于预签名接口，单位为秒，默认 900 秒

Client

Client 对象表示一个 S3 客户端实例。

Bucket 基础 API

名称	类型	参数	返回值	说明
createBucket	方法	`params:object`	`object`	创建存储桶
makeBucket	方法	`params:object`	`object`	`createBucket` 的别名
listBuckets	方法	`params?:object`	`object`	列出所有存储桶
headBucket	方法	`params:object`	`object`	检查 Bucket 元信息
bucketExists	方法	`params:object`	`bool`	判断存储桶是否存在
deleteBucket	方法	`params:object`	`object`	删除存储桶
removeBucket	方法	`params:object`	`object`	`deleteBucket` 的别名
getBucketLocation	方法	`params:object`	`object`	获取 Bucket 所在区域
getBucketAcl	方法	`params:object`	`object`	获取 Bucket ACL
putBucketAcl	方法	`params:object`	`object`	设置 Bucket ACL
getBucketPolicy	方法	`params:object`	`object`	获取 Bucket Policy
putBucketPolicy	方法	`params:object`	`object`	设置 Bucket Policy
deleteBucketPolicy	方法	`params:object`	`object`	删除 Bucket Policy
getBucketPolicyStatus	方法	`params:object`	`object`	获取 Bucket Policy 状态
getBucketTagging	方法	`params:object`	`object`	获取 Bucket Tagging
putBucketTagging	方法	`params:object`	`object`	设置 Bucket Tagging
deleteBucketTagging	方法	`params:object`	`object`	删除 Bucket Tagging
getBucketVersioning	方法	`params:object`	`object`	获取 Bucket Versioning
putBucketVersioning	方法	`params:object`	`object`	设置 Bucket Versioning

Bucket 高级 API

名称	类型	参数	返回值	说明
`getBucketAccelerateConfiguration`	方法	`params:object`	`object`	获取 Accelerate 配置
`putBucketAccelerateConfiguration`	方法	`params:object`	`object`	设置 Accelerate 配置
`getBucketAnalyticsConfiguration`	方法	`params:object`	`object`	获取 Analytics 配置
`putBucketAnalyticsConfiguration`	方法	`params:object`	`object`	设置 Analytics 配置
`deleteBucketAnalyticsConfiguration`	方法	`params:object`	`object`	删除 Analytics 配置
`listBucketAnalyticsConfigurations`	方法	`params:object`	`object`	列出 Analytics 配置
`getBucketCors`	方法	`params:object`	`object`	获取 CORS 配置
`putBucketCors`	方法	`params:object`	`object`	设置 CORS 配置
`deleteBucketCors`	方法	`params:object`	`object`	删除 CORS 配置
`getBucketEncryption`	方法	`params:object`	`object`	获取 Bucket 加密配置
`putBucketEncryption`	方法	`params:object`	`object`	设置 Bucket 加密配置
`deleteBucketEncryption`	方法	`params:object`	`object`	删除 Bucket 加密配置
`getBucketIntelligentTieringConfiguration`	方法	`params:object`	`object`	获取 Intelligent Tiering 配置
`putBucketIntelligentTieringConfiguration`	方法	`params:object`	`object`	设置 Intelligent Tiering 配置
`deleteBucketIntelligentTieringConfiguration`	方法	`params:object`	`object`	删除 Intelligent Tiering 配置
`listBucketIntelligentTieringConfigurations`	方法	`params:object`	`object`	列出 Intelligent Tiering 配置
`getBucketInventoryConfiguration`	方法	`params:object`	`object`	获取 Inventory 配置
`putBucketInventoryConfiguration`	方法	`params:object`	`object`	设置 Inventory 配置
`deleteBucketInventoryConfiguration`	方法	`params:object`	`object`	删除 Inventory 配置
`listBucketInventoryConfigurations`	方法	`params:object`	`object`	列出 Inventory 配置
`getBucketLifecycleConfiguration`	方法	`params:object`	`object`	获取 Lifecycle 配置
`putBucketLifecycleConfiguration`	方法	`params:object`	`object`	设置 Lifecycle 配置
`deleteBucketLifecycle`	方法	`params:object`	`object`	删除 Lifecycle 配置
`getBucketLogging`	方法	`params:object`	`object`	获取 Logging 配置
`putBucketLogging`	方法	`params:object`	`object`	设置 Logging 配置
`getBucketMetricsConfiguration`	方法	`params:object`	`object`	获取 Metrics 配置
`putBucketMetricsConfiguration`	方法	`params:object`	`object`	设置 Metrics 配置
`deleteBucketMetricsConfiguration`	方法	`params:object`	`object`	删除 Metrics 配置
`listBucketMetricsConfigurations`	方法	`params:object`	`object`	列出 Metrics 配置
`getBucketNotificationConfiguration`	方法	`params:object`	`object`	获取 Notification 配置
`putBucketNotificationConfiguration`	方法	`params:object`	`object`	设置 Notification 配置
`getBucketOwnershipControls`	方法	`params:object`	`object`	获取 Ownership Controls
`putBucketOwnershipControls`	方法	`params:object`	`object`	设置 Ownership Controls
`deleteBucketOwnershipControls`	方法	`params:object`	`object`	删除 Ownership Controls
`getBucketReplication`	方法	`params:object`	`object`	获取 Replication 配置
`putBucketReplication`	方法	`params:object`	`object`	设置 Replication 配置
`deleteBucketReplication`	方法	`params:object`	`object`	删除 Replication 配置
`getBucketRequestPayment`	方法	`params:object`	`object`	获取 RequestPayment 配置
`putBucketRequestPayment`	方法	`params:object`	`object`	设置 RequestPayment 配置
`getBucketWebsite`	方法	`params:object`	`object`	获取 Website 配置
`putBucketWebsite`	方法	`params:object`	`object`	设置 Website 配置
`deleteBucketWebsite`	方法	`params:object`	`object`	删除 Website 配置
`getPublicAccessBlock`	方法	`params:object`	`object`	获取 Public Access Block
`putPublicAccessBlock`	方法	`params:object`	`object`	设置 Public Access Block
`deletePublicAccessBlock`	方法	`params:object`	`object`	删除 Public Access Block

Object API

名称	类型	参数	返回值	说明
putObject	方法	`params:object`	`object`	上传对象
getObject	方法	`params:object`	`object`	下载对象
headObject	方法	`params:object`	`object`	获取对象头信息
copyObject	方法	`params:object`	`object`	复制对象
deleteObject	方法	`params:object`	`object`	删除对象
removeObject	方法	`params:object`	`object`	`deleteObject` 的别名
deleteObjects	方法	`params:object`	`object`	批量删除对象
listObjects	方法	`params:object`	`object`	列出对象
listObjectsV2	方法	`params:object`	`object`	列出对象（V2）
listObjectVersions	方法	`params:object`	`object`	列出对象版本
getObjectAcl	方法	`params:object`	`object`	获取对象 ACL
putObjectAcl	方法	`params:object`	`object`	设置对象 ACL
getObjectAttributes	方法	`params:object`	`object`	获取对象属性
getObjectLegalHold	方法	`params:object`	`object`	获取对象 Legal Hold
putObjectLegalHold	方法	`params:object`	`object`	设置对象 Legal Hold
getObjectLockConfiguration	方法	`params:object`	`object`	获取 Object Lock 配置
putObjectLockConfiguration	方法	`params:object`	`object`	设置 Object Lock 配置
getObjectRetention	方法	`params:object`	`object`	获取对象保留策略
putObjectRetention	方法	`params:object`	`object`	设置对象保留策略
getObjectTagging	方法	`params:object`	`object`	获取对象标签
putObjectTagging	方法	`params:object`	`object`	设置对象标签
deleteObjectTagging	方法	`params:object`	`object`	删除对象标签
getObjectTorrent	方法	`params:object`	`object`	获取 Torrent 数据
restoreObject	方法	`params:object`	`object`	恢复归档对象

Multipart Upload API

名称	类型	参数	返回值	说明
createMultipartUpload	方法	`params:object`	`object`	创建分片上传任务
uploadPart	方法	`params:object`	`object`	上传分片
uploadPartCopy	方法	`params:object`	`object`	复制分片
completeMultipartUpload	方法	`params:object`	`object`	完成分片上传
abortMultipartUpload	方法	`params:object`	`object`	中止分片上传
listMultipartUploads	方法	`params:object`	`object`	列出分片上传任务
listParts	方法	`params:object`	`object`	列出已上传分片

Presign API

名称	类型	参数	返回值	说明
presignedGetObject	方法	`params:object`	`object`	获取下载预签名 URL
presignedPutObject	方法	`params:object`	`object`	获取上传预签名 URL
presignedHeadObject	方法	`params:object`	`object`	获取 HeadObject 预签名 URL
presignedDeleteObject	方法	`params:object`	`object`	获取 DeleteObject 预签名 URL
presignedDeleteBucket	方法	`params:object`	`object`	获取 DeleteBucket 预签名 URL
presignedHeadBucket	方法	`params:object`	`object`	获取 HeadBucket 预签名 URL
presignedUploadPart	方法	`params:object`	`object`	获取 UploadPart 预签名 URL

常用方法详解

createBucket

创建一个新的存储桶。

参数

Bucket: 存储桶名称
CreateBucketConfiguration: 可选，创建配置对象

示例

client.createBucket({
    Bucket: "vino-s3-demo",
});

makeBucket

makeBucket 是 createBucket 的别名，方便和 rustfs 的调用方式保持一致。

listBuckets

列出所有存储桶。

示例

const buckets = client.listBuckets({});
console.log("listBuckets:", buckets);

headBucket

检查 Bucket 是否可访问，并返回对应的 Head 结果。

示例

const head = client.headBucket({
    Bucket: "vino-s3-demo",
});
console.log("headBucket:", head);

bucketExists

判断存储桶是否存在。

返回值

bool

示例

const exists = client.bucketExists({
    Bucket: "vino-s3-demo",
});
console.log("bucketExists:", exists);

deleteBucket

删除存储桶。

示例

client.deleteBucket({
    Bucket: "vino-s3-demo",
});

removeBucket

removeBucket 是 deleteBucket 的别名。

putObject

上传对象。

参数

Bucket: 存储桶名称
Key: 对象名称
body: 上传内容，支持 string、buffer、reader
filePath: 本地文件路径
其它字段可直接使用 S3 的标准参数，例如 ContentType、Metadata、ACL

body 和 filePath 至少传一个。

示例

const putRes = client.putObject({
    Bucket: "vino-s3-demo",
    Key: "hello/hello.txt",
    body: "hello from vino s3 plugin",
    ContentType: "text/plain; charset=utf-8",
});

console.log("putObject:", putRes);

通过文件路径上传：

client.putObject({
    Bucket: "vino-s3-demo",
    Key: "images/logo.png",
    filePath: "/tmp/logo.png",
    ContentType: "image/png",
});

getObject

下载对象。

参数

Bucket: 存储桶名称
Key: 对象名称
savePath: 可选，如果传入则将下载结果额外写入本地文件

返回值

返回对象包含：

示例

const res = client.getObject({
    Bucket: "vino-s3-demo",
    Key: "hello/hello.txt",
});

console.log("getObject:", res);

保存到本地：

client.getObject({
    Bucket: "vino-s3-demo",
    Key: "hello/hello.txt",
    savePath: "/tmp/hello.txt",
});

headObject

获取对象头信息。

const head = client.headObject({
    Bucket: "vino-s3-demo",
    Key: "hello/hello.txt",
});
console.log("headObject:", head);

copyObject

复制对象。

const copyRes = client.copyObject({
    Bucket: "vino-s3-demo",
    Key: "copy/hello.txt",
    CopySource: "vino-s3-demo/hello/hello.txt",
});

console.log("copyObject:", copyRes);

deleteObject

删除对象。

client.deleteObject({
    Bucket: "vino-s3-demo",
    Key: "hello/hello.txt",
});

removeObject

removeObject 是 deleteObject 的别名。

deleteObjects

批量删除对象。

client.deleteObjects({
    Bucket: "vino-s3-demo",
    Delete: {
        Objects: [
            {Key: "a.txt"},
            {Key: "b.txt"},
        ],
    },
});

listObjects

列出对象，使用旧版 ListObjects 接口。

const res = client.listObjects({
    Bucket: "vino-s3-demo",
    Prefix: "hello/",
});
console.log("listObjects:", res);

listObjectsV2

列出对象，推荐使用 V2 接口。

const res = client.listObjectsV2({
    Bucket: "vino-s3-demo",
    Prefix: "hello/",
});
console.log("listObjectsV2:", res);

listObjectVersions

列出对象版本。

const res = client.listObjectVersions({
    Bucket: "vino-s3-demo",
    Prefix: "hello/",
});
console.log("listObjectVersions:", res);

getObjectAcl / putObjectAcl

获取或设置对象 ACL。

const acl = client.getObjectAcl({
    Bucket: "vino-s3-demo",
    Key: "hello/hello.txt",
});
console.log("getObjectAcl:", acl);

client.putObjectAcl({
    Bucket: "vino-s3-demo",
    Key: "hello/hello.txt",
    ACL: "private",
});

getObjectTagging / putObjectTagging / deleteObjectTagging

对象标签管理。

client.putObjectTagging({
    Bucket: "vino-s3-demo",
    Key: "hello/hello.txt",
    Tagging: {
        TagSet: [
            {Key: "env", Value: "dev"},
            {Key: "owner", Value: "vino"},
        ],
    },
});

const tags = client.getObjectTagging({
    Bucket: "vino-s3-demo",
    Key: "hello/hello.txt",
});
console.log("getObjectTagging:", tags);

getObjectAttributes

获取对象属性信息，例如 ETag、ObjectSize、StorageClass 等。

const attrs = client.getObjectAttributes({
    Bucket: "vino-s3-demo",
    Key: "hello/hello.txt",
    ObjectAttributes: ["ETag", "ObjectSize"],
});
console.log("getObjectAttributes:", attrs);

getObjectLegalHold / putObjectLegalHold

获取或设置对象 Legal Hold。

getObjectLockConfiguration / putObjectLockConfiguration

获取或设置 Object Lock 配置。

getObjectRetention / putObjectRetention

获取或设置对象保留策略。

getObjectTorrent

获取对象的 Torrent 信息。

const torrent = client.getObjectTorrent({
    Bucket: "vino-s3-demo",
    Key: "hello/hello.txt",
});
console.log("getObjectTorrent:", torrent);

restoreObject

恢复归档对象。

client.restoreObject({
    Bucket: "vino-s3-demo",
    Key: "archive/report.zip",
    RestoreRequest: {
        Days: 3,
    },
});

Multipart Upload

createMultipartUpload

创建分片上传任务。

const upload = client.createMultipartUpload({
    Bucket: "vino-s3-demo",
    Key: "multipart/big-file.bin",
    ContentType: "application/octet-stream",
});

console.log("createMultipartUpload:", upload);

uploadPart

上传单个分片。

const part1 = client.uploadPart({
    Bucket: "vino-s3-demo",
    Key: "multipart/big-file.bin",
    UploadId: upload.UploadId,
    PartNumber: 1,
    body: "part-1-content",
});

console.log("uploadPart:", part1);

也可以通过 filePath 上传本地分片文件。

uploadPartCopy

通过复制现有对象的方式上传分片。

completeMultipartUpload

完成分片上传。

const completeRes = client.completeMultipartUpload({
    Bucket: "vino-s3-demo",
    Key: "multipart/big-file.bin",
    UploadId: upload.UploadId,
    MultipartUpload: {
        Parts: [
            {ETag: part1.ETag, PartNumber: 1},
        ],
    },
});

console.log("completeMultipartUpload:", completeRes);

abortMultipartUpload

中止分片上传。

listMultipartUploads

列出当前 Bucket 中的分片上传任务。

listParts

列出指定上传任务已经上传的分片。

Presigned URL

预签名接口统一返回：

url
method
signedHeader

presignedGetObject

生成下载对象的预签名 URL。

const url = client.presignedGetObject({
    Bucket: "vino-s3-demo",
    Key: "hello/hello.txt",
    expiresIn: 3600,
});

console.log("presignedGetObject:", url);

presignedPutObject

生成上传对象的预签名 URL。

const url = client.presignedPutObject({
    Bucket: "vino-s3-demo",
    Key: "upload/demo.txt",
    ContentType: "text/plain",
    expiresIn: 600,
});

console.log("presignedPutObject:", url);

presignedHeadObject

生成 HeadObject 的预签名 URL。

presignedDeleteObject

生成 DeleteObject 的预签名 URL。

presignedDeleteBucket

生成 DeleteBucket 的预签名 URL。

presignedHeadBucket

生成 HeadBucket 的预签名 URL。

presignedUploadPart

生成 UploadPart 的预签名 URL。

Bucket 高级配置示例

putBucketPolicy

client.putBucketPolicy({
    Bucket: "vino-s3-demo",
    Policy: JSON.stringify({
        Version: "2012-10-17",
        Statement: [
            {
                Sid: "PublicRead",
                Effect: "Allow",
                Principal: "*",
                Action: "s3:GetObject",
                Resource: "arn:aws:s3:::vino-s3-demo/*",
            },
        ],
    }),
});

getBucketPolicy

const policy = client.getBucketPolicy({
    Bucket: "vino-s3-demo",
});
console.log("getBucketPolicy:", policy);

putBucketTagging

client.putBucketTagging({
    Bucket: "vino-s3-demo",
    Tagging: {
        TagSet: [
            {Key: "env", Value: "dev"},
            {Key: "team", Value: "vino"},
        ],
    },
});

getPublicAccessBlock / putPublicAccessBlock

client.putPublicAccessBlock({
    Bucket: "vino-s3-demo",
    PublicAccessBlockConfiguration: {
        BlockPublicAcls: true,
        IgnorePublicAcls: true,
        BlockPublicPolicy: true,
        RestrictPublicBuckets: true,
    },
});

返回值说明

除少数特殊方法外，s3 模块的大多数方法都直接返回 AWS SDK 对应 Output 的 JS 对象版本。

特殊返回值

bucketExists 返回 bool
getObject 返回一个包含 body、contentLength、contentType、etag、metadata 等字段的对象
getObjectTorrent 返回一个包含 body 的对象
所有 presigned* 返回 {url, method, signedHeader}

注意事项

大部分方法的参数结构都与 AWS S3 SDK 的 Input 结构保持一致，建议优先参考官方 S3 参数命名。
putObject、uploadPart 以及对应的预签名接口支持额外的 body 和 filePath 便捷参数。
getObject 支持 savePath，用于将下载结果保存到本地。
当前没有继续封装 SelectObjectContent 和 WriteGetObjectResponse，因为它们需要额外的事件流/特殊响应处理。

S3

ON THIS PAGE