# @beignet/provider-storage-local 中文文档

规范地址：https://npmcn.com/package/%40beignet/provider-storage-local/

版本：0\.0\.65
npm 元数据更新时间：2026-11-07T23:23:16.131Z
中文译文更新时间：2026-11-09T20:55:41.065Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40beignet/provider-storage-local
原文对照：https://npmcn.com/package/%40beignet/provider-storage-local/?lang=original
项目主页：https://github.com/taylorbryant/beignet#readme
源码仓库：https://github.com/taylorbryant/beignet

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

- 包体积（解压后）：83.8 kB，9 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12\.0
- 运行依赖：1 个
- peer 依赖：@beignet/core \>=0\.0\.3 \<1\.0\.0
- 首次发布：2026-05-26T16:50:10.014Z
- 最新版本发布：2026-11-07T23:23:15.955Z
- 近 30 天下载量：1734（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：65（近 12 个月 65 个）

## 中文简介

Beignet 的本地文件系统存储提供者

## 安装

```sh
npm install @beignet/provider-storage-local
```

也可以使用：`pnpm add @beignet/provider-storage-local`、`yarn add @beignet/provider-storage-local`、`bun add @beignet/provider-storage-local`

## README

# @beignet/ 提供者- 存储- 本地

> **运行时间 :** Beignet需要Node.js 22.12或更新. Bun是可选的.

> \[叹息\] Beignet是实验性的α软件. 这个 `0.0.x` 包行为早期 评估,且在框架结算时,API可能在发布之间发生变化.

Beignet 的本地文件系统存储提供商.

提供者安装了应用程序配置 `ctx.ports.storage` 端口 。 用它来 本地开发、需要耐用文件的测试和小型部署 文件系统支持的对象存储已足够.

`createLocalStorageProvider(...)` 返回稳定 `LocalStorageProvider` 类型. `LocalStorageConfig` 描述其有效的配置; Zod 方案 仍为内部.

## 安装

```bash
bun add @beignet/provider-storage-local @beignet/core
```

## 提供者设置

```typescript
import { createLocalStorageProvider } from "@beignet/provider-storage-local";
import { createServer } from "@beignet/core/server";

const server = await createServer({
  ports: basePorts,
  providers: [createLocalStorageProvider()],
  context: ({ ports }) => ({ ports }),
  routes,
});
```

环境变量:

| 变量 | 说明 |
| --- | --- |
| `STORAGE_ROOT` | 写入对象的目录 。 默认为 `storage/app`。 。 。 . |
| `STORAGE_PUBLIC_BASE_URL` | 可选基址返回 `publicUrl(...)` 对于公共物体. |

`beignet doctor --strict` 检查安装的本地存储提供者是 登记在册 `server/providers.ts`。 。 。 .

`STORAGE_PUBLIC_BASE_URL` 可能是一个绝对的 URL,例如 `https://assets.example.com` 或相关路径,例如 `/storage`。 。 。 . 提供者只返回 URL 。 如果您在 Next.js 中使用了相适应路径 应用程序,为公共对象服务 `createStorageRoute`数字 :

```typescript
// app/storage/[...key]/route.ts
import { createStorageRoute } from "@beignet/next";
import { getServer } from "@/server";

export const { GET, HEAD } = createStorageRoute(
  async () => (await getServer()).ports.storage,
  {
    basePath: "/storage",
  },
);
```

## 直接港口工厂

```typescript
import { createLocalStorage } from "@beignet/provider-storage-local";

const storage = createLocalStorage({
  root: "storage/app",
  publicBaseUrl: "/storage",
});
```

提供者提供 `ctx.ports.storage`,标准贝格网 `StoragePort`。它没有特定供应商的逃生舱;使用端口 阅读、写作、公共URL和元数据.

一样 `StoragePort` 与本地文件、内存测试和云对象合作 存储 :

```typescript
await ctx.ports.storage.put("avatars/user_123.png", avatarBytes, {
  contentType: "image/png",
  visibility: "public",
});

const object = await ctx.ports.storage.get("avatars/user_123.png");
const url = await ctx.ports.storage.publicUrl("avatars/user_123.png");
```

## 私人下载

将私有文件存储于 `visibility: "private"`在经过认证的应用路径中, 解析并授权文件记录,然后调用 `createStorageDownloadResponse({ storage, key, fileName })` 从 `@beignet/web` 或者说 `@beignet/next`。它流出一个不可取用的附件并返回 `null` 当对象缺失时,所以路由可以使用其应用错误目录.

`storage.temporaryUrl(key, { expiresInSeconds, fileName? })` 验证其投入 返回时 `{ status: "unsupported" }` 不检查存在。 当地 提供者不会发布过期的链接或公开私人文件。 留着 在任何静态文件目录外存储根; 仅公共存储路径 为明确标记的物体服务.

## 磁盘上的文件

对象如下: `root` 使用他们的存储密钥。 对象元数据是 存储于 a `.beignet-storage-meta` 同一根下方的侧车目录.

存储密钥使用共享 `@beignet/core/ports` 合同:没有空字符串, 控制字符, 空路段, 引导或跟踪 `/`,后鞭打, 或者说 `.` 编号 : `..` 路径段。 这个 `.beignet-storage-meta` 路径段是一个 额外的本地提供者限制,因为它存储了侧车元数据.

## 开发工具

何时 `ctx.ports.devtools` 已安装, 提供者记录存储 业务 `storage` 观者. 事件包括操作名称,密钥, 持续时间,对象大小,能见度,以及是否点击了搜索。 对象机构是 从来没有记录.

## 失败行为

提供者根据需要创建目录并丢弃无效对象密钥, 元数据出错, 文件系统权限失败, 以及读取或写入失败 . 路径 traversal 在触摸文件系统前被拒绝 . 以同一键为对象的变异行为,其根被串用 在一个节点.js进程范围内的顺序,包括通过单独的 本地存储实例. `put(...)` 在键的变异队列前方 分级输入流, 在短承诺锁外, 溪可能读取上一版本的 同一键而不陷入僵局和排队的身体并非全部消耗临时 磁盘空间. `get(...)` 返回一发快照:其元数据和正文仍然保存在 同一版本,即使另一个操作在消耗前覆盖了密钥. 检查身体或呼叫 `await object.cancel()` 关闭未读快照 决了 使用 `stat(...)` 只读元数据.

## 当地测试

利用这一供应商进行当地发展或需要持久的融合测试 文档。 使用应用程序的假冒或内存 `StoragePort` 用于用例测试 只声明存储意图.

## 部署说明

仅在文件系统持久和共享的部署中使用本地存储 所有需要对象的过程。 无服务器和水平缩放 应用程序通常应当使用 `@beignet/provider-storage-s3` 或另一个对象商店. 提供者不协调跨进程或主机的同键写作.

## 许可证

麻省理工学院

## 常见问题

### @beignet/provider-storage-local 是什么？

Beignet 的本地文件系统存储提供者

### 如何安装 @beignet/provider-storage-local？

在项目目录运行 npm install @beignet/provider-storage-local，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@beignet/core（\>=0\.0\.3 \<1\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @beignet/provider-storage-local 支持 TypeScript 吗？

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

### @beignet/provider-storage-local 支持 ESM 还是 CommonJS？

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

### @beignet/provider-storage-local 需要什么版本的 Node\.js？

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

### @beignet/provider-storage-local 可以商用吗？

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

### @beignet/provider-storage-local 的下载量有多少？

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

### @beignet/provider-storage-local 还在维护吗？

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