# @btravstack/storage 中文文档 规范地址：https://npmcn.com/package/%40btravstack/storage/ 版本：0\.58\.0 npm 元数据更新时间：2026-11-07T21:12:38.514Z 中文译文更新时间：2026-11-08T18:08:21.464Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40btravstack/storage 原文对照：https://npmcn.com/package/%40btravstack/storage/?lang=original 项目主页：https://github.com/btravstack/btravstack#readme 源码仓库：https://github.com/btravstack/btravstack ## 关键信息（来自 npm 元数据） - 包体积（解压后）：119 kB，15 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - Node.js 要求：\>=22 - 运行依赖：0 个 - peer 依赖：unthrown ^5\.0\.0，@btravstack/di ^0\.58\.0，@btravstack/core ^0\.58\.0，@aws-sdk/client-s3 ^3\.1000\.0，@btravstack/config ^0\.58\.0，@aws-sdk/s3-request-presigner ^3\.1000\.0 - 首次发布：2026-08-25T16:23:01.506Z - 最新版本发布：2026-11-07T21:12:38.223Z - 近 30 天下载量：7563（2026-10-09 至 2026-11-07，npm 官方下载统计） - 已发布版本数：62（近 12 个月 62 个） ## 中文简介 用于 @btravstack/ core的存储端口:内嵌适配器、带有预签名的S3兼容适配器,以及跨度、计数和记录每个操作的组件 ## 安装 ```sh npm install @btravstack/storage ``` 也可以使用：`pnpm add @btravstack/storage`、`yarn add @btravstack/storage`、`bun add @btravstack/storage` ## README # @btravstack/储存 > 对象存储端口用于 [`@btravstack/core`](https://npmcn.com/package/%40btravstack/core)页:1 `Storage` a 一个 应用程序取决于一个内相适配器,一个S3相容的 预先签名的读取、写取和流出在有界限的内存中,以及跨度, a 计算和每次操作的日志行. 📖 **[文档](https://btravstack.github.io/btravstack/reference/storage)** • 妇女 [API 参考](https://btravstack.github.io/btravstack/api/storage/) ```sh pnpm add @btravstack/storage @btravstack/core @btravstack/config @btravstack/di unthrown ``` 4个同伴依赖关系,加 `@aws-sdk/client-s3` 财务报告和审定财务报表 `@aws-sdk/s3-request-presigner` ——可选的,并且只有在你写作时需要 S3适配器. 仪器不需要自己的同伴: `Logger`, (中文(简体) ), `Tracer` 财务报告和审定财务报表 `Meter` 这取决于是 [内核的端口](https://btravstack.github.io/btravstack/reference/core/observability)。 。 。 . 节点 `>=22`。 。 。 . ## 实例 保存文档,并通过不带的 URL 读取 全权证书: ```ts import { Port as InvoicePort, Provider as InvoiceProvider, } from "@btravstack/di"; import { Storage } from "@btravstack/storage"; import type { AsyncResult } from "unthrown"; class Invoices extends InvoicePort("ReadmeInvoices")<{ readonly store: ( tenantId: string, id: string, pdf: Uint8Array, ) => AsyncResult; readonly link: ( tenantId: string, id: string, ) => AsyncResult; }> {} // The tenant is in the key because the port has no slot for one — the same // rule a cache key follows. const keyFor = (tenantId: string, id: string) => `invoices/${tenantId}/${id}.pdf`; export const invoices = InvoiceProvider(Invoices)({ inject: { storage: Storage }, sync: ({ storage }) => ({ store: (tenantId, id, pdf) => storage .put(keyFor(tenantId, id), pdf, { contentType: "application/pdf" }) // A document that failed to store is YOUR decision to make; here it // is swallowed because an observer already recorded it and // counted it one layer down. .recoverErrCases((matcher) => matcher.with(P.tag("StorageUnavailable"), P.tag("InvalidStorageOptions"), P.tag("ChecksumMismatch"), () => undefined), ), // Serving bytes through your own process is the anti-pattern this arm // exists to avoid: the caller fetches the object directly, for a minute. link: (tenantId, id) => storage .presignedUrl(keyFor(tenantId, id), { ttlMs: 60_000 }) .recoverErrCases((matcher) => matcher .with(P.tag("StorageUnavailable"), () => undefined) .with(P.tag("PresignNotSupported"), () => undefined), ), }), }); ``` 组成——适配器是唯一的决定, 在这里决定了,没有别的地方: ```ts import { storage } from "@btravstack/storage"; import { s3Storage } from "@btravstack/storage/s3"; export const InvoicesApp = Module("InvoicesApp")({ imports: [ // Instrumented by default, which is why `observability()` and `otel()` // Every call is reported through `Observers`. Drop the two modules // below and this composition is unchanged — it just reports to nobody. storage({ adapter: s3Storage() }), observability(), otel(), ], provides: [invoices], exports: [Invoices, Logger], }); ``` ## 选项 | 选项 | 何处 | 这是什么 | | --- | --- | --- | | `sha256` 编号 : `metadata` | `put` 编号 : `putIfAbsent` 和流 | 校验写入摘要并解剖地描述对象 | | `checksum` 编号 : `metadata` | `copy` | 计算 SHA-256 服务器侧并替换描述 | | `kmsKeyId` | 写、复制和 `presignedUpload` | 选择每个对象 SSE- KMS; 上传客户端发送两个签名的加密信头 | | `adapter` | `storage({ adapter })` | 适配器模块提供 `StorageBackend` 所需数额 | | `STORAGE_S3_ENDPOINT` | 环境,读作 `s3Storage()` | 商店的终点——需要 | | `STORAGE_S3_BUCKET` | 环境 | 所需桶 | | `STORAGE_S3_ACCESS_KEY_ID` 编号 : `STORAGE_S3_SECRET_ACCESS_KEY` | 环境 | 全权证书要求 | | `STORAGE_S3_REGION` | 环境 | 默认 `us-east-1` | | `STORAGE_S3_MAX_SOCKETS` 编号 : `maxSockets` | 环境,或 `s3Storage({...})` | 套接字每一次呼叫, 但不包含流出共享—— 默认 `50`,SDK's(SDK's | | `STORAGE_S3_STREAM_MAX_SOCKETS` 编号 : `streamMaxSockets` | 环境,或 `s3Storage({...})` | 串行调用自有调用池, 及其约束- 默认 `50` | | `STORAGE_S3_CONNECTION_TIMEOUT_MS` 编号 : `connectionTimeoutMs` | 环境,或 `s3Storage({...})` | 尝试等待套接字多久——默认 `0`,无 | | `STORAGE_S3_SOCKET_TIMEOUT_MS` 编号 : `socketTimeoutMs` | 环境,或 `s3Storage({...})` | 尝试的套接字可以保持闲置多久——默认 `0`,无 | | `STORAGE_S3_REQUEST_TIMEOUT_MS` 编号 : `requestTimeoutMs` | 环境,或 `s3Storage({...})` | 尝试等待商店回答多久 — 默认 `0`,无 | | `STORAGE_S3_STREAM_CONNECTION_TIMEOUT_MS` 编号 : `streamConnectionTimeoutMs` | 环境,或 `s3Storage({...})` | 流池自身的连接超时——默认 `connectionTimeoutMs` | | `STORAGE_S3_STREAM_SOCKET_TIMEOUT_MS` 编号 : `streamSocketTimeoutMs` | 环境,或 `s3Storage({...})` | 流池自设套接字超时——默认 `socketTimeoutMs` | | `STORAGE_S3_STREAM_REQUEST_TIMEOUT_MS` 编号 : `streamRequestTimeoutMs` | 环境,或 `s3Storage({...})` | 流池自身的请求超时——默认 `requestTimeoutMs` | 完整表——默认,语义和推理——活在 [参考页](https://btravstack.github.io/btravstack/reference/storage), (中文(简体) ), 这张名单是详细的. ## 它决定什么,它没有 **决定** 失踪物体是普通的答案而不是过错 (计算) `not_found`,没有过错线),即持有的密钥下 `putIfAbsent` 是一个普通的答案( a)`ObjectExists`数字 `exists`),该 `delete` 是天能的,那个 `copy` 财务报告和审定财务报表 `head` 字节从不通过这个过程移动,写作可以验证SHA-256并解析地公布用户元数据,复制取代元数据并可以计算SHA-256服务器侧面,预先签名的上传可以要求每个对象KMS键,流出字节从不离开部分对象(多段上传,在任何故障上中止),流出传输有自有的套接字池并被拒绝()`StreamPoolFull`数字 `saturated`而不是排队 一旦它满了 签名前询问商店什么也没有—— 以及无法签名的适配器 而不是刻出只生产失败的 URL . **它没有决定** 您的密钥长相, 是否失败的写入 无法满足您的请求, 或者链接应该存在多久 。 没有列名,没有 桶管理——每个原因都在 [参考页](https://btravstack.github.io/btravstack/reference/storage), (中文(简体) ), 同样的推理是 [`AGENTS.md`](https://npmcn.com/package/%40btravstack/storage/AGENTS.md) 用于贡献者. ## 许可证 麻省理工学院 接受指定下载 `contentDisposition`, (中文(简体) ), `contentType` 财务报告和审定财务报表 `cacheControl` 反应超过。 见 [存储引用](https://btravstack.github.io/btravstack/reference/storage) 用于签名和 Unicode 文件名语义. ## 常见问题 ### @btravstack/storage 是什么？ 用于 @btravstack/ core的存储端口:内嵌适配器、带有预签名的S3兼容适配器,以及跨度、计数和记录每个操作的组件 ### 如何安装 @btravstack/storage？ 在项目目录运行 npm install @btravstack/storage，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：unthrown（^5\.0\.0）、@btravstack/di（^0\.58\.0）、@btravstack/core（^0\.58\.0）、@btravstack/config（^0\.58\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @btravstack/storage 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @btravstack/storage 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @btravstack/storage 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @btravstack/storage 可以商用吗？ @btravstack/storage 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @btravstack/storage 的下载量有多少？ 根据 npm 官方下载统计，@btravstack/storage 在 2026/10/09 – 2026/11/07 这 30 天内被下载 7,563 次，日均约 252 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @btravstack/storage 还在维护吗？ 最新版本 0\.58\.0 发布于 2026/11/08（今天）；至今共发布 62 个版本，其中过去 12 个月发布了 62 个；首次发布于 2026/08/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。