# @crvouga/mockingbird-service-s3 中文文档

规范地址：https://npmcn.com/package/%40crvouga/mockingbird-service-s3/

版本：4\.1\.0
npm 元数据更新时间：2026-11-11T02:34:56.348Z
中文译文更新时间：2026-11-11T02:14:06.569Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40crvouga/mockingbird-service-s3
原文对照：https://npmcn.com/package/%40crvouga/mockingbird-service-s3/?lang=original
项目主页：https://github.com/crvouga/mockingbird/tree/main/packages/service/s3#readme
源码仓库：https://github.com/crvouga/mockingbird

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：6.3 MB，26 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-09-23T00:02:27.016Z
- 最新版本发布：2026-11-11T02:34:55.981Z
- 近 30 天下载量：17335（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：41（近 12 个月 41 个）

## 中文简介

准确回答MinIO的状态 S3 模拟器: 每一桶,对象,多部分,版本,对象锁定,策略和认证 API,对照已录入的MinIO文字记录进行校验.

## 安装

```sh
npm install @crvouga/mockingbird-service-s3
```

也可以使用：`pnpm add @crvouga/mockingbird-service-s3`、`yarn add @crvouga/mockingbird-service-s3`、`bun add @crvouga/mockingbird-service-s3`

## README

# @crvouga/mockingbird-service-s3 (英语)

> 本地模拟器。 真正的API合同. 部分 [嘲笑鸟](https://github.com/crvouga/mockingbird)。 。 。 .

精确回答为 [米尼奥](https://github.com/minio/minio) 做,所以它下降为MinIO,亚马逊S3和其他S3兼容存储在测试中. 每个行为都由差分的甲骨文所支撑:370个脚本情景(约3,800个HTTP交换)被记录在了针对MinIO的 `RELEASE.2025-10-15T17-29-55Z`,以及 `bun test` 重放每个对仿真器,并且需要相同的状态,头和XML字节来表示字节.

## 安装

```bash
npm install -D @crvouga/mockingbird-service-s3
```

仅限无害环境管理。 节点22+或Bun 1.2+.

## 使用量

将 SDK 端点指向模拟器并启用路径式地址 。 Fixture 证书被验证为预签请求;默认对为 `fixture` 编号 : `fixture`。 。 。 .

```ts
import { CreateBucketCommand, GetObjectCommand, PutObjectCommand, S3Client } from "@aws-sdk/client-s3"
import { createServer } from "@crvouga/mockingbird-service-s3/server"

// Test setup: start the emulator and point the SDK's endpoint at it.
const server = await createServer()
const s3 = new S3Client({
  endpoint: server.url,
  region: "us-east-1",
  forcePathStyle: true,
  credentials: { accessKeyId: "fixture", secretAccessKey: "fixture" },
})

// Application code: the S3 SDK calls it already makes.
await s3.send(new CreateBucketCommand({ Bucket: "fixtures" }))
await s3.send(
  new PutObjectCommand({ Bucket: "fixtures", Key: "result.bin", Body: new Uint8Array([0, 255]) }),
)
const object = await s3.send(new GetObjectCommand({ Bucket: "fixtures", Key: "result.bin" }))
console.log(await object.Body?.transformToByteArray()) // Uint8Array(2) [ 0, 255 ]

await server.close()
```

设置应用程序的 S3 端点环境变量到服务器 URL 及其区域到 `us-east-1`。 。 。 .

### 支助行动

MinIO的S3路由器所服务的一切,都有MinIO的先行,验证顺序,出错代码和消息(出自MinIO自己的出错表):

-   **弹夹**: CreateBucket(位置约束,对象锁定旗),HeadBucket,DevedBucket(包含. `x-minio-force-delete`), ListBuckets, GetBucketLocation, Get/PutBucketVersioning (包括MinIO的被排除在外的前缀), Get/Put/DeleteBucket政策和GetBucket政策状态, Get/Put/DeleteBucketTlaging, Get/Put/DeleteBucketLife循环, Get/Put/DeleteBucketEncrypt, Get/Put/DeleteBucketReplextation, Get/PutOboxLockfignation, ACL,网站,CL,加速,要求支付和记录分站,以及Minio的监听通知和复制扩展.
-   **对象**: Put Object, Get Object, Head Object(系统和用户元数据,有条件读取和写入,每个范围表, `partNumber`, (中文(简体) ), `response-*` 更换、校验和 CRC32/CRC32C/CRC64NVME/SHA1/SHA256 `x-amz-checksum-mode`),复制对象(元数据和标记指令,复制源条件,版本),删除对象和删除对象(删除标记,无效版本),Get/Put/DeletobjectTlaging,Get/Putobject保留,Get/PutobjectLegalHold,Get/PutObjectAcl,GetObjectAtizes,还原对象,选择对象(CSV和JSON输入,基本SQL,事件流框架),浏览器POST上传(POST政策,V4和V2表签名).
-   **列名**: 列出对象 V1, V2 和 `metadata=true`,列表objectversions,包括MinIO的标记和截取行为.
-   **多块**: 创建、上传部分、上传部分、完整部分、中止部分、列表部分、列表多部分加载,并附有部分校验和 `<md5>-N` ETAG (英语).
-   **认证**: SigV4 标题并预签,流线 `aws-chunked` (签名块和签名或未签名的拖车),SigV2头和预先签名,请求时间 skew,以及通过桶政策匿名访问.

`GetObjectLambda` 财务报告和审定财务报表 `PutObjectExtract` (雪球自动取出)答案 `NotImplemented`。 。 。 .

### 认证模式

-   `authentication: "lenient"` (默认):未签名的请求充当桶主和信头签名不检查,所以很简单 `fetch` 做测试 已指定 URL 仍在对照 `credentials` (默认) `fixture` 编号 : `fixture`) (中文(简体) ).
-   `authentication: "strict"`: MinIO的认证准确无误. 每项请求都必须用下列语句签名: `credentials`,而匿名请求只有在桶政策允许的情况下才允许. 甲骨文运行于此模式.

`region` (默认) `us-east-1`)是签署区域和 `x-amz-bucket-region` 头曰.

### 从米尼欧出发的地方

-   **Bucket CORS 键盘**:MinIO只给"桶"CORS API打分,因此模拟器保留了Amazon S3的有记载的行为. 存储 `CORSConfiguration` 执行:飞行前通过第一个比对规则回答或拒绝使用 `403 AccessForbidden`,并匹配实际请求 `Access-Control-*` 头. 这不是神谕验证.
-   **虚拟托管地址**数字 : `Host: <bucket>.<base host>` 名称桶( 基准主机默认为 `localhost`; 设置 `virtualHosts`,或 `--virtual-host a,b`,仅供路径样式使用.
-   **体积**数字 : `createServer` 接受最高为每PUT或部分5个GiB(S3的极限;MinIO为5个TiB). `createServer({ maxBodyBytes })` 低点.
-   **名单** 总是读取实时数据, MinIO从第一页的快照中为后页服务.

### 预言

`oracle/` 存储库中保存着带子、情景和录制的MINIO记录誊本. `bun oracle/run.ts` 重播他们与一个活的MINIO, `--record` 刷新记录;见 [甲骨文/README.md](https://github.com/crvouga/mockingbird/tree/main/packages/service/s3/oracle)。 。 。 .

### 管理和确定性控制

-   `GET/POST /__admin/objects` 检查一个对象的元数据或种子; `GET /__admin/objects/:bucket/:key` 下载其字节.
-   `GET /__admin/uploads` 检查活动上传和部分元数据.
-   预设的缺陷是 `slow_down`, (中文(简体) ), `access_denied`, (中文(简体) ), `expired_token`和一发 `truncate_stream`。通用断层可以失败或重置下一个部分请求.
-   推进共享仿真器时钟通过 `/__admin/clock` 以过期过期的 URL .
-   对象写出,复制,多段补全,并删除发布S3形通知. 通过运行时间配置 HTTP 汇 `webhooks` 选项或共享的 webhook 管理员路由; 发送尝试和重试出现在下面 `/__admin/webhooks`。 。 。 .

共享运行时间还提供健康,重置,日记,衡量标准,时间表和断层路径. 选择孤立状态 `x-mockingbird-namespace`, (中文(简体) ), `/__admin/ns/<name>`,或者SigV4访问键映射.

### 故意不模拟

SSE-C和SSE-KMS加密(MinIO需要TLS和一个KMS给他们),IAM用户和根证书和桶政策以外的政策,实际应用生命周期规则或复制,以及真正的SQS送出. SQS消费者可以通过配置的HTTP槽来使用所捕获的通知有效载荷.

## API 密码

-   `S3API`, (中文(简体) ), `S3APIOptions`:获取处理器和配置.
-   `S3Notification`, (中文(简体) ), `S3Object` (单位:千美元)`ObjectVersion`, (中文(简体) ), `S3SeedObject`, (中文(简体) ), `BucketRecord`, (中文(简体) ), `MultipartUpload`, (中文(简体) ), `MultipartPart`: 通知、状态和固定类型.
-   `createRuntime`, (中文(简体) ), `S3Runtime`, (中文(简体) ), `S3RuntimeOptions`:完整的"鸟"跑步时间和"网球"中枢.
-   `S3_NAMESPACE`, (中文(简体) ), `S3_PRESETS`, (中文(简体) ), `accessKeyCredential`:常数和故障控制.
-   `S3_MAX_UPLOAD_BYTES`: 默认请求正文限制 (5 GiB) for `createServer`。 。 。 .
-   `document`, (中文(简体) ), `operationIds`, (中文(简体) ), `supportedOperationIds`: 生成了 OpenAPI 元数据.
-   `createServer`, (中文(简体) ), `S3ServerOptions`, (中文(简体) ), `DEFAULT_PORT`, (中文(简体) ), `serveTarget` 从 `./server`:节点HTTP适配器和CLI集成.

甲骨文 : [米尼奥](https://github.com/minio/minio) `RELEASE.2025-10-15T17-29-55Z`,与 [亚马逊 S3 API 参考](https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html) 为桶 CORS.

## 常见问题

### @crvouga/mockingbird-service-s3 是什么？

准确回答MinIO的状态 S3 模拟器: 每一桶,对象,多部分,版本,对象锁定,策略和认证 API,对照已录入的MinIO文字记录进行校验\.

### 如何安装 @crvouga/mockingbird-service-s3？

在项目目录运行 npm install @crvouga/mockingbird-service-s3，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mockingbird-s3，可以用 npx mockingbird-s3 直接运行。

### @crvouga/mockingbird-service-s3 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @crvouga/mockingbird-service-s3 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @crvouga/mockingbird-service-s3 可以商用吗？

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

### @crvouga/mockingbird-service-s3 的下载量有多少？

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

### @crvouga/mockingbird-service-s3 还在维护吗？

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