# @antelopejs/file-storage-s3 中文文档

规范地址：https://npmcn.com/package/%40antelopejs/file-storage-s3/

版本：0\.1\.10
npm 元数据更新时间：2026-11-04T15:44:55.507Z
中文译文更新时间：2026-11-06T16:52:49.759Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40antelopejs/file-storage-s3
原文对照：https://npmcn.com/package/%40antelopejs/file-storage-s3/?lang=original
项目主页：https://github.com/AntelopeJS/interface-file-storage/tree/main/docs
源码仓库：https://github.com/AntelopeJS/file-storage-s3

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

- 包体积（解压后）：185 kB，48 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2026-03-23T18:50:04.700Z
- 最新版本发布：2026-11-04T15:44:55.176Z
- 近 30 天下载量：2684（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

S3兼容的藏羚羊JS(AWS S3, Cloudflare R2)存储模块,执行文件存储界面,并预发了 URL

## 安装

```sh
npm install @antelopejs/file-storage-s3
```

也可以使用：`pnpm add @antelopejs/file-storage-s3`、`yarn add @antelopejs/file-storage-s3`、`bun add @antelopejs/file-storage-s3`

## README

# `@antelopejs/file-storage-s3`

[![npm](https://img.shields.io/npm/v/@antelopejs/file-storage-s3?style=for-the-badge&labelColor=000000&color=000000)](https://www.npmjs.com/package/@antelopejs/file-storage-s3) [![License](https://img.shields.io/npm/l/@antelopejs/file-storage-s3?style=for-the-badge&labelColor=000000&color=000000)](https://npmcn.com/package/%40antelopejs/file-storage-s3/LICENSE) [![Discord](https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000)](https://discord.gg/g4pFt6eXqu) [![Documentation](https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000)](https://github.com/AntelopeJS/interface-file-storage/tree/main/docs)

用于S3兼容对象存储的AntelopeJS文件存储模块,如AWS S3和Cloudflare R2. 用这个 `@aws-sdk/client-s3`,客户端通过预先签名的URL直接从桶上上传并读取文件.

## 接口

| 接口 | 文档 |
| --- | --- |
| [`@antelopejs/interface-file-storage`](https://github.com/AntelopeJS/interface-file-storage) | [文件存储](https://github.com/AntelopeJS/interface-file-storage/tree/main/docs) |

界面页面文档上传、阅读、能见度、元数据、中继和宣传.

## 安装

```bash
ajs project modules add @antelopejs/file-storage-s3
```

模块没有默认配置, 所以添加一个 `config` 块为 `default` 在项目启动前存储.

## 配置

```typescript
import { defineConfig } from "@antelopejs/interface-core/config";

export default defineConfig({
  name: "my-project",
  modules: {
    "file-storage-s3": {
      source: {
        type: "package",
        package: "@antelopejs/file-storage-s3",
        version: "^0.1.5",
      },
      config: {
        default: {
          endpoint: "https://<account>.r2.cloudflarestorage.com",
          region: "auto",
          accessKeyId: "<access-key-id>",
          secretAccessKey: "<secret-access-key>",
          bucket: "app-files",
          attachmentPrivateBucket: "app-private-files",
          publicUrl: "https://cdn.example.com",
          defaultVisibility: "private",
          defaultUploadExpiration: 3600,
          defaultReadExpiration: 300,
          stagingExpirationDays: 1,
          assumePrivateBuckets: false,
        },
        storages: {
          media: {
            endpoint: "https://<account>.r2.cloudflarestorage.com",
            region: "auto",
            accessKeyId: "<access-key-id>",
            secretAccessKey: "<secret-access-key>",
            bucket: "app-media",
            publicUrl: "https://media.example.com",
            defaultVisibility: "public",
            defaultUploadExpiration: 3600,
            defaultReadExpiration: 300,
          },
        },
      },
    },
  },
  envOverrides: {
    S3_SECRET_ACCESS_KEY:
      "modules.file-storage-s3.config.default.secretAccessKey",
  },
});
```

| 密钥 | 说明 |
| --- | --- |
| `endpoint`, (中文(简体) ), `region` | S3端点与区域. R2 使用区域 `auto`。 。 。 . |
| `accessKeyId`, (中文(简体) ), `secretAccessKey` | S3客户端的全权证书. |
| `bucket` | 拿着档案的巴基特. |
| `attachmentPrivateBucket` | 上传请求的可选桶 `visibility: "private"`,远离公众 `bucket`没有它,这样的上传投出. |
| `publicUrl` | 可选公共来源 `bucket`。从 `<publicUrl>/<resourceKey>`没有 `publicUrl`,通过一个预先签名的URL读取. |
| `defaultVisibility` | 上传文件的可见度,没有, `"public"` 或者说 `"private"`。 。 。 . |
| `defaultUploadExpiration` | 上传URL的寿命, 以秒计 . |
| `defaultReadExpiration` | 私人的寿命读取 URL, 以秒计, 当呼叫者设置无 . |
| `stagingExpirationDays` | 可选的 启动时,模块设置了一个生命周期规则 `bucket` 财务报告和审定财务报表 `attachmentPrivateBucket` 过了这么多天,文件就过期了 当你的基础设施 管理生命周期规则时, 放弃它. |
| `assumePrivateBuckets` | 可选的, `false` 默认。 放松无法通过私人桶的验证. |

除了可选的钥匙以外,所有钥匙都需要. `default` 持有主存储. `storages` 添加带有相同密钥的命名存储器,以及 `storage` 参数。 名称 `default` 保留在 `storages`,模块拒绝从它开始.

## 快开始

在处理上传的模块中,添加接口:

```bash
pnpm add @antelopejs/interface-file-storage
```

```typescript
import {
  CreateReadUrl,
  CreateUploadUrl,
} from "@antelopejs/interface-file-storage";

const upload = await CreateUploadUrl(
  { filename: "avatar.png", size: 52_000, mimetype: "image/png" },
  { maxSize: 1_000_000, allowedMimetypes: ["image/png", "image/jpeg"] },
);

const read = await CreateReadUrl(upload.resourceKey);
```

客户端发送文件 `PUT upload.uploadUrl` 和每个标题 `upload.headers`,不变,然后从 `read.url`。 。 。 .

## 部署前

-   上传 URL 签名 `If-None-Match: *` 条件,所以上传不会取代已有对象。 提供者必须执行有条件的 `PUT`,而桶 CORS规则必须允许 `if-none-match` 头曰.
-   模块核查 `attachmentPrivateBucket` 在使用前屏蔽所有公共访问。 MinIO 和 Hetzner 对象存储需要 `assumePrivateBuckets: true`。 。 。 .
-   S3 在小写中存储元数据密钥, 所以 `GetFileMetadata` 返回时 `tenantid` 用于发送的上传 `tenantId`。只有大小写不同的两个键才使上传投出.

[乌巴解组织](https://npmcn.com/package/%40antelopejs/file-storage-s3/UPLOADS.md) 详细说明这些保证。 它涵盖只创建的上传,促销,隐私和过期,私人桶验证,元数据密钥和CORS.

## 文档

-   [文件存储](https://github.com/AntelopeJS/interface-file-storage/tree/main/docs) 文档 `@antelopejs/interface-file-storage` 与本模块执行的合同.
-   [配置](https://framework.antelopejs.com/docs/concepts/configuration) 包括模块来源, `config` 区块和配置变量 `antelope.config.ts`。 。 。 .

## 兼容性

| 软件包 | 支助 | 测试过 |
| --- | --- | --- |
| `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` | `0.2.4` |
| `@antelopejs/interface-file-storage` | `>=0.1.6 <0.2.0` | `0.1.6` |

`.nvmrc` 名称为 Node.js 发行用于开发。 测试与 Moto 图像相对 `.github/release-services.yml` 针.

## 捐款

测试需要一个 [摩托](https://github.com/getmoto/moto) 打开 S3 服务器 `127.0.0.1:5005`。启动 CI 使用的 :

```bash
docker compose -f .github/release-services.yml up -d --wait
```

然后检查:

```bash
pnpm install
pnpm lint
pnpm format:check
pnpm knip
pnpm test           # build, then ajs module test
```

测试还管理着共用的兼容套件,包括: `@antelopejs/interface-file-storage`。阅读 [捐款准则](https://npmcn.com/package/%40antelopejs/file-storage-s3/CONTRIBUTING.md) 在打开拉出请求之前.

## 许可证

[阿帕奇 - 2.0](https://npmcn.com/package/%40antelopejs/file-storage-s3/LICENSE)

## 常见问题

### @antelopejs/file-storage-s3 是什么？

S3兼容的藏羚羊JS\(AWS S3, Cloudflare R2\)存储模块,执行文件存储界面,并预发了 URL

### 如何安装 @antelopejs/file-storage-s3？

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

### @antelopejs/file-storage-s3 支持 TypeScript 吗？

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

### @antelopejs/file-storage-s3 支持 ESM 还是 CommonJS？

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

### @antelopejs/file-storage-s3 可以商用吗？

@antelopejs/file-storage-s3 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @antelopejs/file-storage-s3 的下载量有多少？

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

### @antelopejs/file-storage-s3 还在维护吗？

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