# @beaugmented/s3-sandbox 中文文档

规范地址：https://npmcn.com/package/%40beaugmented/s3-sandbox/

版本：0\.1\.2
npm 元数据更新时间：2026-10-14T15:41:40.922Z
中文译文更新时间：2026-11-07T20:00:44.099Z
软件包许可：MPL-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40beaugmented/s3-sandbox
原文对照：https://npmcn.com/package/%40beaugmented/s3-sandbox/?lang=original
项目主页：https://github.com/beaugmented/s3-sandbox
源码仓库：https://github.com/beaugmented/s3-sandbox

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

- 包体积（解压后）：732 kB，53 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：26\.11\.1
- 运行依赖：8 个
- 首次发布：2026-10-14T06:28:02.350Z
- 最新版本发布：2026-10-14T15:41:40.496Z
- 近 30 天下载量：23176（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

一个本地的S3兼容服务器,用于孤立的开发和测试

## 安装

```sh
npm install @beaugmented/s3-sandbox
```

也可以使用：`pnpm add @beaugmented/s3-sandbox`、`yarn add @beaugmented/s3-sandbox`、`bun add @beaugmented/s3-sandbox`

## README

# @ beaugmented/ s3- sandbox (英语)

本地S3兼容服务器,用于开发和孤立测试,来源于 [S3rver 软件](https://github.com/jamhall/s3rver)要求节点26.11.1和无害环境管理.

这个叉子由 [增加数](https://github.com/beaugmented)。请报告问题并请求支持 [此寄存器](https://github.com/beaugmented/s3-sandbox/issues)。 。 。 .

## 安装和运行

```sh
pnpm add -D @beaugmented/s3-sandbox
pnpm exec s3-sandbox --directory ./s3-data --address 127.0.0.1 --port 4568
pnpm exec s3-sandbox --help
```

CLI 在需要时创建数据目录. `--configure-bucket <name> [configs...]` 预配置带有可选 XML 文件并可以重复的桶. `--key` 财务报告和审定财务报表 `--cert` 启用 TLS. `--no-vhost-buckets` 禁用桶主机名 .

## 程序化 API

```ts
import { mkdtempSync, rmSync } from "node:fs"
import { tmpdir } from "node:os"
import path from "node:path"
import S3Sandbox from "@beaugmented/s3-sandbox"

const directory = mkdtempSync(path.join(tmpdir(), "s3-test-"))
const sandbox = new S3Sandbox({
    directory,
    address: "127.0.0.1",
    port: 0,
    silent: true,
    configureBuckets: [{ name: "test-bucket" }],
})

try {
    const { port } = await sandbox.run()
    // Use http://127.0.0.1:${port} as the client's endpoint.
} finally {
    await sandbox.close()
    rmSync(directory, { recursive: true, force: true })
}
```

为程序实例使用一个专用的现有目录。 端口 `0` 选择可用的端口; `run()` 决定收听地址。 在测试清理中关闭服务器 。 除非 `resetOnClose` 已启用.

| 选项 | 默认 | 含义 |
| --- | --- | --- |
| `directory` | OS 临时目录 + `s3-sandbox` | 文件系统存储根 . |
| `address` | `localhost` | 主机或IP绑定. |
| `port` | `4568` | HTTP 端口; `0` 选择可用的端口. |
| `silent` | `false` | 禁止请求日志. |
| `key`, (中文(简体) ), `cert`, (中文(简体) ), `pfx` | 未设定 | 节点 HTTPS 服务器选项 . |
| `serviceEndpoint` | `amazonaws.com` | 虚拟主机的服务主机名后缀. |
| `vhostBuckets` | `true` | 识别主机名中的桶名 . |
| `resetOnClose` | `false` | 删除服务器关闭时的所有桶数据 . |
| `allowMismatchedSignatures` | `false` | 接受有不匹配签名的完善请求 . |
| `configureBuckets` | `[]` | Bucket名和可选的生 XML 字符串或缓冲. |

`run(callback)` 财务报告和审定财务报表 `close(callback)` 保留回调表并返回实例. `callback()` 及其别名 `getMiddleware()` 返回一个适合 `http.createServer()`调用 `configureBuckets()` 在直接安装处理器之前. `reset()` 清除存储的桶数据.

服务器内部使用Hono并扩展了节点 `EventEmitter`. 它的公用API是S3沙盒生命周期和事件API;HTTP框架继承和上下文定制不支持.

### 在霍诺上山

`getHonoMiddleware()` 将沙盒装入Hono应用程序中 由它的节点适配器提供 穿过路线中使用的同一种挂载路径, 不带后行斜线; 挂起根时省略它 。 适配器提供S3签名和流上传所需的原始节点请求.

```ts
import { Hono } from "hono"
import { serve, type HttpBindings } from "@hono/node-server"

await sandbox.configureBuckets()
const app = new Hono<{ Bindings: HttpBindings }>()
app.use("/s3/*", sandbox.getHonoMiddleware("/s3"))
const server = serve({
    fetch: app.fetch,
    port: 4568,
    overrideGlobalObjects: false,
})
// Use http://localhost:4568/s3 as the S3 client's endpoint.
// Close the host server during cleanup; sandbox.run() was not called.
await new Promise<void>((resolve, reject) =>
    server.close((error) => (error ? reject(error) : resolve())),
)
```

## AWS SDK v3 (英语)

使用 `S3RVER` 用于签名密钥和启用路径式访问 :

```ts
import { S3Client } from "@aws-sdk/client-s3"

const client = new S3Client({
    endpoint: "http://127.0.0.1:4568",
    region: "us-east-1",
    forcePathStyle: true,
    credentials: { accessKeyId: "S3RVER", secretAccessKey: "S3RVER" },
    requestChecksumCalculation: "WHEN_REQUIRED",
    responseChecksumValidation: "WHEN_REQUIRED",
})
```

校验和设置选择了沙盒目前执行的S3行为. 目前SDK v3请求和遗留的SDK v2客户合同进行测试.

## 支助行动

-   Buckets:创建,删除,列表,对象列表中包含前缀,划界符,标记和续作符,位置查询,以及CORS/website配置.
-   对象:PUT,多部分形式 POST,GET,HEAD,复制,单批删除,标记,元数据,字节范围,以及假ACL响应.
-   多段上传:启动,上传/复制部分,并完成.
-   认证:签名版本2和4, 预先签名的URL, 并签名块上传.
-   网站:索引/错误文档,重定向,路由规则,以及虚拟主机请求.

这是S3部分执行,目的是在当地进行开发和测试。 不支持的操作返回 S3 形状的错误 .

对象读取支持单字节范围,包括 `bytes=0-0`后缀区域,例如: `bytes=-10`。超出对象大小的尾部和后缀长度被夹到可用的字节上。 对空对象返回的不满意范围和范围 `416 InvalidRange`; 变形和多范围头被忽略.

对于多部分 POST 上传, 提交 `key`,元数据,以及响应控制字段 `file` 页:1 即使该部分没有文件名,也要存储文件内容流 。 服务器存储了第一个文件并忽略了后来的形式字段.

## Bucket 配置和网站

通过套件导出解析捆绑的 XML 示例 :

```ts
import { readFileSync } from "node:fs"
import S3Sandbox from "@beaugmented/s3-sandbox"

const cors = new URL(
    import.meta.resolve("@beaugmented/s3-sandbox/example/cors.xml"),
)
const website = new URL(
    import.meta.resolve("@beaugmented/s3-sandbox/example/website.xml"),
)
const sandbox = new S3Sandbox({
    directory: "./s3-data",
    configureBuckets: [
        {
            name: "site.local",
            configs: [readFileSync(cors), readFileSync(website)],
        },
    ],
})
```

网站请求可以使用桶路径, 如 `http://localhost:4568/site.local/`。用于 `http://site.local:4568/`,解决 `site.local` 改为 `127.0.0.1` 当地。 上传的索引文档必须匹配桶的网站配置.

参见 AWS 示例 [(简体中文)](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketPUTcors.html) 财务报告和审定财务报表 [网站配置](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketPUTwebsite.html)。 。 。 .

## 活动

执行对象操作前订阅 :

```ts
sandbox.on("event", (event) => {
    console.log(event.Records[0].eventName)
})
```

PUT、POST、COPY和DELETE 操作在 [S3事件结构](https://docs.aws.amazon.com/AmazonS3/latest/userguide/notification-content-structure.html)。 。 。 .

## 许可证和归属

此分叉根据 [MPL - 2.0 导弹](https://npmcn.com/package/%40beaugmented/s3-sandbox/LICENSE)杰米·霍尔是 [S3rver 软件](https://github.com/jamhall/s3rver),是该项目的基础. [通知](https://npmcn.com/package/%40beaugmented/s3-sandbox/NOTICE) 识别继承的材料及其原件 [麻省理工学院通知](https://npmcn.com/package/%40beaugmented/s3-sandbox/LICENSES/MIT.txt)。保存上游文件系统后缀.

被吸收的多部分执行也保留了Brian White的 [麻省理工学院通知](https://npmcn.com/package/%40beaugmented/s3-sandbox/LICENSES/busboy-MIT.txt)。 。 。 .

## 常见问题

### @beaugmented/s3-sandbox 是什么？

一个本地的S3兼容服务器,用于孤立的开发和测试

### 如何安装 @beaugmented/s3-sandbox？

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

### @beaugmented/s3-sandbox 支持 TypeScript 吗？

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

### @beaugmented/s3-sandbox 支持 ESM 还是 CommonJS？

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

### @beaugmented/s3-sandbox 需要什么版本的 Node\.js？

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

### @beaugmented/s3-sandbox 可以商用吗？

@beaugmented/s3-sandbox 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @beaugmented/s3-sandbox 的下载量有多少？

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

### @beaugmented/s3-sandbox 还在维护吗？

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