@auth0/s3

中文文档

1.0.1发布于 2025/12/12MITCommonJS近 30 天下载 16.9万

Amazon S3 上传/下載文件的客户端

文档目录28 节

安装
特征
概要
创建客户端
从现有的 AWS 创建客户端。 S3 对象
上传文件到 S3
从 S3 下载文件
将目录同步到 S3
提示
API 文档
第3条. AWS
s3. 创建客户端( 选项)
s3. get PublicUrl(桶,键, [桶Location]) 互联网档案馆的存檔,存档日期2013-12-21
s3. Get PublicUrlHttp( 按钮, 密钥)
客户端.uploadFile(段落)
客户端. downloadFile(段落)
客户端. 下行负荷缓冲器( s3Params)
客户端. 下行装入Stream( s3Params)
客户端.list 对象(段落)
客户端. delete 对象( s3Params)
客户端.uploadDir(段落)
客户端. downloadDir( 参数)
客户端.deleteDir(s3Params)
客户端.复制对象(s3Params)
客户端.move 对象(s3Params)
实例
检查文件是否在 S3 中存在
测试

高级亚马逊 S3 客户端

叉从 https://github.com/andrewrk/node-s3-客户端

安装

npm install @auth0/s3 --save

特征

当 S3 返回错误时, 自动重试可配置次数 .
包括逻辑, 当有 1000 对象限制时, 提出多个请求 .
确定S3请求最大平行性限制的能力. 后退被推到并行队列的末尾.
能够同步到 S3 的目录 .
进度报告.
支持任意大小的文件(最高为 S3 的最大 5 TB 对象大小限制).
使用并行多段上传快速上传大文件.
使用heuristics来计算多部分ETags客户端,以避免上传或不必要地下载文件.
根据文件扩展名自动为上传提供内容-Type.
支持第三方S3兼容平台服务如Ceph

Ưμ㼯A s3cmd: (中文(简体) ) s 3- cli (英语)。。。 .

概要

创建客户端

var s3 = require('s3');

var client = s3.createClient({
  maxAsyncS3: 20,     // this is the default
  s3RetryCount: 3,    // this is the default
  s3RetryDelay: 1000, // this is the default
  multipartUploadThreshold: 20971520, // this is the default (20 MB)
  multipartUploadSize: 15728640, // this is the default (15 MB)
  s3Options: {
    accessKeyId: "your s3 key",
    secretAccessKey: "your s3 secret",
    region: "your region",
    // endpoint: 's3.yourdomain.com',
    // sslEnabled: false
    // any other options are passed to new AWS.S3()
    // See: http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#constructor-property
  },
});

从现有的 AWS 创建客户端。 S3 对象

var s3 = require('s3');
var awsS3Client = new AWS.S3(s3Options);
var options = {
  s3Client: awsS3Client,
  // more options available. See API docs below.
};
var client = s3.createClient(options);

上传文件到 S3

var params = {
  localFile: "some/local/file",

  s3Params: {
    Bucket: "s3 bucket name",
    Key: "some/remote/file",
    // other options supported by putObject, except Body and ContentLength.
    // See: http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#putObject-property
  },
};
var uploader = client.uploadFile(params);
uploader.on('error', function(err) {
  console.error("unable to upload:", err.stack);
});
uploader.on('progress', function() {
  console.log("progress", uploader.progressMd5Amount,
            uploader.progressAmount, uploader.progressTotal);
});
uploader.on('end', function() {
  console.log("done uploading");
});

从 S3 下载文件

var params = {
  localFile: "some/local/file",

  s3Params: {
    Bucket: "s3 bucket name",
    Key: "some/remote/file",
    // other options supported by getObject
    // See: http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getObject-property
  },
};
var downloader = client.downloadFile(params);
downloader.on('error', function(err) {
  console.error("unable to download:", err.stack);
});
downloader.on('progress', function() {
  console.log("progress", downloader.progressAmount, downloader.progressTotal);
});
downloader.on('end', function() {
  console.log("done downloading");
});

将目录同步到 S3

var params = {
  localDir: "some/local/dir",
  deleteRemoved: true, // default false, whether to remove s3 objects
                       // that have no corresponding local file.

  s3Params: {
    Bucket: "s3 bucket name",
    Prefix: "some/remote/dir/",
    // other options supported by putObject, except Body and ContentLength.
    // See: http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#putObject-property
  },
};
var uploader = client.uploadDir(params);
uploader.on('error', function(err) {
  console.error("unable to sync:", err.stack);
});
uploader.on('progress', function() {
  console.log("progress", uploader.progressAmount, uploader.progressTotal);
});
uploader.on('end', function() {
  console.log("done uploading");
});

提示

考虑在 http 财务报告和审定财务报表 https 全球探员这将在使用时改善带宽 uploadDir 财务报告和审定财务报表 downloadDir 函数。例如:
```
http.globalAgent.maxSockets = https.globalAgent.maxSockets = 20;
```

API 文档

第3条. AWS

这包含了对aws-sdk模块的引用. 这是有效使用的案例此模块和下级 aws- sdk 模块同步进行.

s3. 创建客户端( 选项)

创建 S3 客户端 .

options数字 :

s3Client - 可选的,一个实例 AWS.S3。如果您提供了 s3Options。。。 .
s3Options -可选的提供时留空 s3Client。。。 .
- Ưμ㼯A new AWS.S3()数字 : http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#构造器-财产
maxAsyncS3 - 该客户端将同时请求的最大数量永远可以打开 S3. 默认为 20。。。 .
s3RetryCount - 多少次尝试一次S3行动,然后放弃. 默认 3.
s3RetryDelay - 在重试 S3 之前等待多少毫秒操作。默认1000.
multipartUploadThreshold - 如果一个文件是这么多字节或更多,它将通过多部分请求上传。默认为 20MB 。最低为5MB. 最大值为5GB.
multipartUploadSize - 当通过多部分上传时,这是部分大小. 最小尺寸为5MB. 最大尺寸为5GB. 默认为 15MB. 请注意: S3的多段上传最多有一万个部件, 所以如果这个值是太小了,它会被忽略以获得最低的必要价值需要上传文件.

s3. get PublicUrl(桶,键, [桶Location]) 互联网档案馆的存檔,存档日期2013-12-21

bucket S3水桶
key S3 键
bucketLocation 字符串,其中之一:
- ""(默认) - 美国标准
- "欧西一"
- "我们西一"
- "我们西部2"
- 东南一号
- "ap-东南-2"
- 东北一号
- "莎-东一"

您可以使用此 API 程序查找您的桶位置 : http://docs.aws.amazon.com/AWS-JavaScriptSDK/latest/AWS/S3.html#getBucketLocation-财产

返回这样的字符串 :

https://s3.amazonaws.com/bucket/key

或者,如果你不在美国标准:

https://s3-eu-west-1.amazonaws.com/bucket/key

s3. Get PublicUrlHttp( 按钮, 密钥)

bucket S3 弹匣
key S3 键

工作于任意区域,并返回这样的字符串 :

http://bucket.s3.amazonaws.com/key

客户端.uploadFile(段落)

见 http://docs.aws.amazon.com/AWS-JavaScriptSDK/latest/AWS/S3.html#put Object-property (英语)

params数字 :

s3Params: 传递给 AWS SDK 的参数 putObject。。。 .
localFile: 要上传到 S3 的磁盘上的文件路径 .
(可选) defaultContentType: 除非你明确设置 ContentType 参数在 s3Params,它会自动为您设定基于文件扩展名 localFile。如果扩展未被认可, defaultContentType 将改为使用。默认为 application/octet-stream。。。 .

使用 AWS SDK 的区别 putObject 这个:

这与文件有关,而不是流或缓冲.
如果上传完成时报告过的MD5不匹配,则重复进行.
如果文件大小足够大,请使用多段上传以上传部分平行.
根据客户端的重试设置进行重试.
进度报告.
设置 ContentType 如果您不提供,则基于文件扩展名.

返回 a EventEmitter 带有这些属性的:

progressMd5Amount
progressAmount
progressTotal

这些事件:

'error' (err)
'end' (data) - 成功上传文件时释放
- data 是同一个对象,您从 putObject 在 AWS SDK 中
'progress' - 当 progressMd5Amount, (中文(简体) ), progressAmount,以及 progressTotal 属性改变。请注意: 上传失败时向后退, 必须重试 .
'fileOpened' (fdSlicer) - 当 localFile 已打开。文件随 fd 剪贴机模块,因为我们可能需要从文件中的多个位置读取同时. fdSlicer 是您可以调用的对象 createReadStream(options)。更多信息请参见fd-slicer README.
'fileClosed' - 当 localFile 已经关闭 .

这些方法:

abort() -打这个电话来阻止搜索行动.

客户端. downloadFile(段落)

见 http://docs.aws.amazon.com/AWS-JavaScriptSDK/latest/AWS/S3.html#getobject-property (中文(简体) )

params数字 :

localFile - 将 s3 对象写入磁盘上的目的地路径
s3Params: 传递给 AWS SDK 的参数 getObject。。。 .

使用 AWS SDK 的区别 getObject 这个:

这与目的文件有关,而不是流或缓冲.
如果所报的MD5在下载完成后不匹配,则会重试.
根据客户端的重试设置进行重试.
进度报告.

返回 a EventEmitter 带有这些属性的:

progressAmount
progressTotal

这些事件:

'error' (err)
'end' - 成功下载文件时释放
'progress' - 当 progressAmount 财务报告和审定财务报表 progressTotal 属性改变.

客户端. 下行负荷缓冲器( s3Params)

http://docs.aws.amazon.com/AWS-JavaScriptSDK/latest/AWS/S3.html#getobject-property (中文(简体) )

s3Params: 传递给 AWS SDK 的参数 getObject。。。 .

使用 AWS SDK 的区别 getObject 这个:

这只能用缓冲器.
如果所报的MD5在下载完成后不匹配,则会重试.
根据客户端的重试设置进行重试.
进度报告.

返回 a EventEmitter 带有这些属性的:

progressAmount
progressTotal

这些事件:

'error' (err)
'end' (buffer) - 文件下载成功后释放 . buffer 是一个 Buffer 包含对象数据.
'progress' - 当 progressAmount 财务报告和审定财务报表 progressTotal 属性改变.

客户端. 下行装入Stream( s3Params)

http://docs.aws.amazon.com/AWS-JavaScriptSDK/latest/AWS/S3.html#getobject-property (中文(简体) )

s3Params: 传递给 AWS SDK 的参数 getObject。。。 .

使用 AWS SDK 的区别 getObject 这个:

这只有一条溪流才有效.

如果您想要重试, 进度, 或MD5 检查, 您必须自己编码 .

回返a ReadableStream 连同这些额外活动:

'httpHeaders' (statusCode, headers) - 包含HTTP响应头和状态代码.

客户端.list 对象(段落)

见 http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#list Objects-property (中文(简体) )

params数字 :

s3Params - 传递给AWS SDK的参数 listObjects。。。 .
(可选) recursive - 说吧 true 或者说 false 您是否想要重现输入目录。默认 false。。。 .

请注意,如果你设置 Delimiter 内 s3Params 然后,你会得到一个列表您指定的目录中的对象和文件夹。你也许不想设定 recursive 改为 true ,同时规定 Delimiter 因为这将引起每个目录的请求。如果您想要所有共享对象前缀,离开 Delimiter 选项 null 或者说 undefined。。。 .

记得 s3Params.Prefix 以斜线结束/除非你们正在请求上一级列名,在这种情况下 s3Params.Prefix 应为空字符串.

使用 AWS SDK 的区别 listObjects 这个:

根据客户端的重试设置进行重试.
支持递归目录列表 .
如果要列出的对象数量大于 1000 , 则会提出多个请求 .

返回 a EventEmitter 带有这些属性的:

progressAmount
objectsFound
dirsFound

这些事件:

'error' (err)
'end' - 上市时已公布,不再公布“数据”事件.
'data' (data) - 当发现一批物体时发射。这是一样 data aWS SDK中的对象.
'progress' - 当 progressAmount, (中文(简体) ), objectsFound,以及 dirsFound 属性改变.

这些方法:

abort() -打这个电话来阻止搜索行动.

客户端. delete 对象( s3Params)

见 http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#delete Objects-property 互联网档案馆的存檔,存档日期2013-12-22

s3Params 都一样.

使用 AWS SDK 的区别 deleteObjects 这个:

根据客户端的重试设置进行重试.
如果想要删除的对象数量是超过1000.

返回 a EventEmitter 带有这些属性的:

progressAmount
progressTotal

这些事件:

'error' (err)
'end' - 在所有对象被删除时发射.
'progress' - 发射时 progressAmount 或者说 progressTotal 属性改变.
'data' (data) - 当一个请求完成时,释放。也许还有更多.

客户端.uploadDir(段落)

将整个目录同步到 S3 .

params数字 :

localDir - 本地文件系统中的源路径以同步到 S3
s3Params
- Prefix (必须)
- Bucket (必须)
(可选) deleteRemoved - 删除没有相应本地文件的 s3 对象. 默认虚假
(可选) getS3Params - 函数,用于调用每个文件需要上传。您可以用这个跳过一些文件。见下文.
(可选) defaultContentType: 除非你明确设置 ContentType 参数在 s3Params,它会自动为您设定基于文件扩展名 localFile。如果扩展未被认可, defaultContentType 将改为使用。默认为 application/octet-stream。。。 .
(可选) followSymlinks - 把它设定为 false 忽略符号链接. 默认为 true。。。 .

function getS3Params(localFile, stat, callback) {
  // call callback like this:
  var err = new Error(...); // only if there is an error
  var s3Params = { // if there is no error
    ContentType: getMimeType(localFile), // just an example
  };
  // pass `null` for `s3Params` if you want to skip uploading this file.
  callback(err, s3Params);
}

返回 a EventEmitter 带有这些属性的:

progressAmount
progressTotal
progressMd5Amount
progressMd5Total
deleteAmount
deleteTotal
filesFound
objectsFound
doneFindingFiles
doneFindingObjects
doneMd5

这些事件:

'error' (err)
'end' - 所有文件上传后释放
'progress' - 当任何上述特性发生变化时发射.
'fileUploadStart' (localFilePath, s3Key) - 当文件开始时释放上传中.
'fileUploadEnd' (localFilePath, s3Key) - 文件成功时释放完成上传.

uploadDir 这样的工作:

开始列出目标的所有 S3 对象 PrefixS3担保返回要排序的对象.
同时,将所有文件递归到 localDir。。。 .
一旦找到所有本地文件,我们就对其进行排序(与S3类型相同).
接下来我们逐一浏览排序的本地文件列表,计算 MD5金额.
现在S3对象上市和MD5和Sum计算正在平行进行. 作为每一个操作进展我们比较两个排序列表并肩, 一次一个地在他们身上,上传那些MD5没有金额的文件匹配远程对象(或远程对象缺失),如果 deleteRemoved 设置,删除其相应的本地对象缺少文件 .

客户端. downloadDir( 参数)

从 S3 同步整个目录 .

params数字 :

localDir - 本地文件系统中的目标目录以同步到
s3Params
- Prefix (必须)
- Bucket (必须)
(可选) deleteRemoved - 删除没有相应 s3 对象的本地文件。默认 false
(可选) getS3Params - 函数,用于调用每个对象需要下载。您可以用它来跳过一些对象的下载 . 见下文.
(可选) followSymlinks - 把它设定为 false 忽略符号链接. 默认为 true。。。 .

function getS3Params(localFile, s3Object, callback) {
  // localFile is the destination path where the object will be written to
  // s3Object is same as one element in the `Contents` array from here:
  // http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#listObjects-property

  // call callback like this:
  var err = new Error(...); // only if there is an error
  var s3Params = { // if there is no error
    VersionId: "abcd", // just an example
  };
  // pass `null` for `s3Params` if you want to skip downloading this object.
  callback(err, s3Params);
}

返回 a EventEmitter 带有这些属性的:

progressAmount
progressTotal
progressMd5Amount
progressMd5Total
deleteAmount
deleteTotal
filesFound
objectsFound
doneFindingFiles
doneFindingObjects
doneMd5

这些事件:

'error' (err)
'end' - 下载所有文件时释放
'progress' - 当以上任何进展属性发生变化时发射
'fileDownloadStart' (localFilePath, s3Key) - 当文件开始时释放下载中.
'fileDownloadEnd' (localFilePath, s3Key) - 文件成功时释放完成下载.

downloadDir 这样的工作:

开始列出目标的所有 S3 对象 PrefixS3担保返回要排序的对象.
同时,将所有文件递归到 localDir。。。 .
一旦找到所有本地文件,我们就对其进行排序(与S3类型相同).
接下来我们逐一浏览排序的本地文件列表,计算 MD5金额.
现在S3对象上市和MD5和Sum计算正在平行进行. 作为每一个操作进展我们比较两个排序列表并肩, 一次一个地在他们身上,下载那些MD5没有金额的东西匹配本地文件(或缺少本地文件),如果 deleteRemoved 设置,删除其相应对象的本地文件失踪了.

客户端.deleteDir(s3Params)

删除 S3 上的整个目录.

s3Params数字 :

Bucket
Prefix
(可选) MFA

返回 a EventEmitter 带有这些属性的:

progressAmount
progressTotal

这些事件:

'error' (err)
'end' - 在所有对象被删除时发射.
'progress' - 发射时 progressAmount 或者说 progressTotal 属性改变.

deleteDir 这样的工作:

开始逐一列出桶中的所有对象。 S3 返回1,000个对象每一答复.
对于每个回放和清单的物体在桶, 立即发送全部删除请求.

客户端.复制对象(s3Params)

见 http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#复制对象-财产

s3Params 都一样别忘了 CopySource 必须包含源桶名称以及源密钥名称.

使用 AWS SDK 的区别 copyObject 这个:

根据客户端的重试设置进行重试.

返回 a EventEmitter 在这些活动中:

'error' (err)
'end' (data)

客户端.move 对象(s3Params)

见 http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#复制对象-财产

s3Params 都一样别忘了 CopySource 必须包含源桶名称以及源密钥名称.

盖下,这个用 copyObject 接下来 deleteObjects 只有在复制成功 .

返回 a EventEmitter 在这些活动中:

'error' (err)
'copySuccess' (data)
'end' (data)

实例

检查文件是否在 S3 中存在

使用 AWS SDK , 您可以发送一个 HEAD 请求, 它会告诉你文件是否存在 Key。。。 .

见 http://docs.aws.amazon.com/AWS-JavaScriptSDK/latest/AWS/S3.html#头项对象-财产

var client = require('s3').createClient({ /* options */ });
client.s3.headObject({
  Bucket: 's3 bucket name',
  Key: 'some/remote/file'
}, function(err, data) {
  if (err) {
    // file does not exist (err.statusCode == 404)
    return;
  }
  // file exists
});

测试

aws-vault exec <profile> -- S3_KEY=<valid_s3_key> npm test

测试上传和下载大量数据到和从S3. 测试暂停时间设定为40秒,因为互联网连通性很强.

版本与发布记录

@auth0/s3 共发布 2 个版本，首次发布于 2018/11/02；过去 12 个月发布了 1 个版本。

版本	发布日期	距今
`1.0.1`latest	2025/12/12	10 个月前
`1.0.0`	2018/11/02	8 年前

关于 @auth0/s3 的常见问题

@auth0/s3 是什么？

Amazon S3 上传/下載文件的客户端

如何安装 @auth0/s3？

在项目目录运行 npm install @auth0/s3，或使用 pnpm add / yarn add / bun add。

@auth0/s3 支持 TypeScript 吗？

该包的 package.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/auth0__s3 是否存在。

@auth0/s3 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require()；在 ES Module 项目中也可以用 import 引入（Node.js 会把 module.exports 作为默认导出）。

@auth0/s3 需要什么版本的 Node.js？

package.json 的 engines 字段要求 Node.js >=8.0.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

@auth0/s3 可以商用吗？

@auth0/s3 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

@auth0/s3 的下载量有多少？

根据 npm 官方下载统计，@auth0/s3 在 2026/10/07 – 2026/11/05 这 30 天内被下载 168,900 次，日均约 5,630 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@auth0/s3 还在维护吗？

最新版本 1.0.1 发布于 2025/12/12（10 个月前）；至今共发布 2 个版本，其中过去 12 个月发布了 1 个；首次发布于 2018/11/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

npm install @auth0/s3

pnpmpnpm add @auth0/s3
yarnyarn add @auth0/s3
bunbun add @auth0/s3

在你的项目目录中运行此命令。

近 30 天下载

168,900

约 16.9万次日均 5,630 次

统计周期 2026/10/07 – 2026/11/05
数据来自 npm 官方下载统计，今天更新

最新版本1.0.1发布于 10 个月前

开源许可MIT宽松许可

包体积77.6 kB7 个文件 · 解压后

运行依赖9 个

模块格式CommonJS

TypeScript未声明类型可查找 @types/auth0__s3

Node.js>=8.0.0

发布版本2 个近 12 个月 1 个

首次发布2018/11/028 年前

元数据更新2026/07/14

每一个软件包背后，
都有分享与创造的人。

@auth0/s3

高级亚马逊 S3 客户端

安装

特征

概要

创建客户端

从现有的 AWS 创建客户端 。 S3 对象

上传文件到 S3

从 S3 下载文件

将目录同步到 S3

提示

API 文档

第3条. AWS

s3. 创建客户端( 选项)

s3. get PublicUrl(桶,键, [桶Location]) 互联网档案馆的存檔,存档日期2013-12-21

s3. Get PublicUrlHttp( 按钮, 密钥)

客户端.uploadFile(段落)

客户端. downloadFile(段落)

客户端. 下行负荷缓冲器( s3Params)

客户端. 下行装入Stream( s3Params)

客户端.list 对象(段落)

客户端. delete 对象( s3Params)

客户端.uploadDir(段落)

客户端. downloadDir( 参数)

客户端.deleteDir(s3Params)

客户端.复制对象(s3Params)

客户端.move 对象(s3Params)

实例

检查文件是否在 S3 中存在

测试

版本与发布记录

关于 @auth0/s3 的常见问题

@auth0/s3 是什么？

如何安装 @auth0/s3？

@auth0/s3 支持 TypeScript 吗？

@auth0/s3 支持 ESM 还是 CommonJS？

@auth0/s3 需要什么版本的 Node.js？

@auth0/s3 可以商用吗？

@auth0/s3 的下载量有多少？

@auth0/s3 还在维护吗？

从现有的 AWS 创建客户端。 S3 对象