# @flystorage/file-storage 中文文档

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

版本：1\.2\.2
npm 元数据更新时间：2026-01-24T09:52:19.088Z
中文译文更新时间：2026-11-15T03:04:36.532Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40flystorage/file-storage
原文对照：https://npmcn.com/package/%40flystorage/file-storage/?lang=original
项目主页：https://flystorage.dev/
源码仓库：https://github.com/duna-oss/flystorage

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

- 包体积（解压后）：84 kB，26 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2023-11-30T14:04:28.064Z
- 最新版本发布：2026-01-24T09:52:18.967Z
- 近 30 天下载量：89091（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 2 个）

## 中文简介

文件存储抽象:多文件系统,一个API.

## 安装

```sh
npm install @flystorage/file-storage
```

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

## README

![](https://raw.githubusercontent.com/duna-oss/flystorage/main/flystorage.svg)

# 飞行仓库

Flystorage是用于NodeJS和TypeScript的文件存储抽象. 这是一个80/20的解决方案 围绕一系列目标:

-   提供易于使用的直向API.
-   允许应用程序代码未知文件存储位置 .
-   实际平滑地克服潜在的存储差异.
-   展示一个Aync/await基于API, 承诺一路.
-   文件权限摘要使用"可视性".
-   实际测试 通过真正的整合, _嘲笑是不欢迎的_。 。 。 .
-   站在巨人的肩上,尽可能使用官方的供应商包.

### 飞行场是什么

Flystorage是用于通用文件存储用例的情况. 这不是API的 任何特定文件系统。 这是一个通用的解决方案,不会只执行特性 特定存储执行。 会有没有满足的用具 仅仅因为不能以合理的方式加以抽象.

## 能力

-   使用字符串 QQ 缓冲 QQ 可读/ 流写入文件
-   将文件读取为流、 字符串或 Uint8Array
-   列出目录/前缀的内容,(shallow and deep).
-   元数据,例如; mime-类型, 上次修改的时间戳, 文件大小 .
-   显示或计算文件的校验和 .
-   在文件不存在时删除不失败的文件 .
-   使用抽象可见度设定权限
-   删除目录( 及其包含的任何文件)
-   生成公共 URL .
-   生成临时( 已签名) URL .
-   从浏览器上安全直接上传.
-   移动文件
-   复制文件

## 适配器

-   [本地文件系统](https://www.npmjs.com/package/@flystorage/local-fs)
-   [AWS S3( 使用 V3 SDK)](https://www.npmjs.com/package/@flystorage/aws-s3)
-   [Azure Blob 存储器](https://www.npmjs.com/package/@flystorage/azure-storage-blob)
-   [测试实施(模拟)](https://www.npmjs.com/package/@flystorage/in-memory)
-   [谷歌云存储](https://www.npmjs.com/package/@flystorage/google-cloud-storage)
-   [混沌适配器装饰器](https://www.npmjs.com/package/@flystorage/chaos)

## 使用量

安装主软件包和可能需要的任何适配器:

```bash
npm i -S @flystorage/file-storage

# for using AWS S3
npm i -S @flystorage/aws-s3

# for using the local filesystem
npm i -S @flystorage/local-fs
```

## 本地用户

```typescript
import {resolve} from 'node:path';
import {createReadStream} from 'node:fs';
import {FileStorage, Visibility} from '@flystorage/file-storage';
import {LocalStorageAdapter} from '@flystorage/local-fs';

/**
 * SETUP
 **/

const rootDirectory = resolve(process.cwd(), 'my-files');
const storage = new FileStorage(new LocalStorageAdapter(rootDirectory));

/**
 * USAGE
 **/

// Write using a string
await storage.write('write-from-a-string.txt', 'file contents');

// Write using a stream
const stream = createReadStream(resolve(process.cwd(), 'test-files/picture.png'));
await storage.write('picture.png', stream);

// Write with visibility (permissions).
await storage.write('public.txt', 'debug', {
    visibility: Visibility.PUBLIC, // mode: 0o644
});
await storage.write('private.txt', 'debug', {
    visibility: Visibility.PRIVATE, // mode: 0o600
});

// List directory contents
const contentsAsAsyncGenerator = storage.list('', {deep: true});

for await (const item of contentsAsAsyncGenerator) {
    console.log(item.path);

    if (item.isFile) {
        // do something with the file
    } else if (item.isDirectory) {
        // do something with the directory
    }
}

// Delete a file
await storage.deleteFile('some-file.txt');

// Delete a directory (with all contents)
await storage.deleteDirectory('some-directory');
```

## 作者

Flystorage由维护者建造 [飞行系统](https://flysystem.thephpleague.com/)页:1 pHP 的文件系统抽象。 这带来了过来 十年的文件系统抽象经验.

## 常见问题

### @flystorage/file-storage 是什么？

文件存储抽象:多文件系统,一个API\.

### 如何安装 @flystorage/file-storage？

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

### @flystorage/file-storage 支持 TypeScript 吗？

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

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

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

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

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

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

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

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

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