# @sourceloop/file-utils 中文文档

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

版本：0\.7\.2
npm 元数据更新时间：2026-11-02T11:32:45.600Z
中文译文更新时间：2026-11-02T13:43:09.004Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40sourceloop/file-utils
原文对照：https://npmcn.com/package/%40sourceloop/file-utils/?lang=original
项目主页：https://github.com/sourcefuse/loopback4-microservice-catalog#readme
源码仓库：https://github.com/sourcefuse/loopback4-microservice-catalog

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

- 包体积（解压后）：119 kB，123 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：22 \|\| 24
- 运行依赖：12 个
- peer 依赖：@loopback/core ^7\.0\.3
- 首次发布：2024-08-14T16:16:38.664Z
- 最新版本发布：2026-11-02T11:32:45.216Z
- 已发布版本数：31（近 12 个月 9 个）

## 中文简介

用于loopback应用程序的文件上传和多部分相关实用程序

## 安装

```sh
npm install @sourceloop/file-utils
```

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

## README

# 文件跑龙套

这个包提供了在LoopBack 4微服务中添加文件上传和验证的实用程序。

## 安装

安装软件包的命令如下：

```shell
npm install @sourceloop/file-utils
```

## 使用

-   绑定组件并添加需求绑定。

```ts
this.bind(AWSS3Bindings.Config).to({
  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  region: process.env.AWS_REGION,
} as AwsS3Config);

this.component(FileUtilComponent);
```

有两种方法可以在控制器中接受多部分请求

-   添加 `multipartRequestBody` 修饰符到你想要接受带有/不带有文件的多部分请求体的控制器方法

```ts
  @post(`/parents/no-model-metadata`)
  @response(200, {
    description: 'Parent without config model instance',
    content: {
      'application/json': {schema: getModelSchemaRef(ParentWithConfig)},
    },
  })
  async createWithOutModelConfig(
    @multipartRequestBody(ParentWithConfig)
    data: ParentWithModelConfig,
  ): Promise<void> {
    ...
  }
```

你可以阅读更多关于这个装饰 [在这里](https://npmcn.com/package/%40sourceloop/file-utils/#readme-multipart-request-decorator)

-   添加 `file` 修饰符到控制器方法，您希望在其中处理文件

```ts
@file(getJsonSchema(Parent) as SchemaObject, ['file'], ['.csv'])
data: ParentWithFile,
```

您可以阅读更多关于文件装饰器及其参数的信息 [在这里](https://npmcn.com/package/%40sourceloop/file-utils/#readme-file-decorator)

### 多部分请求装饰器

这个装饰器允许 `multipart/form-data` 请求主体，包含任意多的字段和文件。它要求您为请求定义一个模型，如果任何字段是文件类型，则需要用 `@fileProperty` -

```ts
@model()
export class ParentWithConfig extends Entity {
  @property({
    type: 'string',
    id: true,
  })
  id?: string;

  @property({
    type: 'string',
    required: true,
  })
  name: string;

  // file field
  @fileProperty({
    type: 'object',
    // you can configure individual fields here
    validators: [FileTypeValidator],
    extensions: ['.png', '.txt'],
  })
  file: Express.Multer.File;

  constructor(data?: Partial<ParentWithConfig>) {
    super(data);
  }
}
```

### 文件装饰

这个装饰器被设计用来处理单个文件的上传 `multipart/form-data` 请求。它提供了一种结构化的方式来管理请求主体中的多个字段，包括文件字段。

#### 参数

-   **模式** （`SchemaObject`):
    
    -   请求主体的模式对象。在您有多个字段并且希望以结构化的方式处理这些数据的情况下，它非常有用。例如，如果您的请求有一个文件字段和一个名称字段，您可以用这些字段定义一个模式对象，并将其传递给装饰器。文件字段将在模式中被标记为二进制。
-   **filefield** （`string[]`):
    
    -   模式中表示文件上传的字段。所以根据上面的例子，你可以通过 `['file']` 到此参数。这将在模式中将文件字段标记为二进制。
-   **allowedExtensions** （`string[]`):
    
    -   上传文件允许的文件扩展名。
-   **storageOptions** （`IFileStorageOptions<T>`):
    
    -   文件存储的选项。这支持任何多存储引擎类。默认情况下，它使用内存存储，并且包还提供S3存储引擎。

#### S3存储引擎

默认情况下，文件存储在内存中，但是这个包也提供了一个基于s3的存储引擎，要使用它，您需要安装 `loopback4-s3` 包- `npm i loopback4-s3` 然后你可以在构型属性中给出它 `@fileProperty` 或者 `@file` 修饰符。您还需要全局绑定它，如下所示

```ts
import {MulterS3Storage} from '@sourceloop/file-utils/s3';
...
// inside component/application constructor
this.service(MulterS3Storage);
```

### 文件验证

默认情况下，包提供了两个验证器

-   `FileTypeValidator` -根据配置验证文件的类型
-   `FileNameValidator` -验证文件名，以避免文件名中出现某些特殊字符

您可以编写自己的自定义验证器，并使用 `@fileValidator` 装饰器，每个验证器必须实现 `IFileValidator` 界面,

```ts
@fileValidator()
export class FileSizeValidator implements IFileValidator {
  ...
}
```

### ClamAV

该包提供了一个基于ClamAV的验证器，要使用它，您需要安装 `clamscan` 包- `npm i clamscan` 然后在应用程序中绑定验证器。这是…

```ts
this.service(ClamAVValidator);
```

### 限制的配置

的实例来配置多实例 `IFileLimitsGetter` 在 `FileUtilBindings.LimitProvider` 关键,

```ts
this.bind(FileUtilBindings.LimitProvider).to({
  get() {
    // this is the default limits in the package
    fileSize: FIVE * MB, // 5 MB
    files: 1,
  }
});


// OR you can use a class or any other type of binding as long as it returns
// an instance of `IFileLimitsGetter-
this.bind(FileUtilBindings.LimitProvider).toClass(MulterConfigService);
```

您还需要在模型文件中使用以下配置来更新模型装饰器-

```ts
@model({
  settings: {multer: {limitsProvider: true}},
})
export class TestModel extends Entity {}
```

## 贡献

欢迎投稿！请参阅 [贡献指南](https://npmcn.com/package/DEVELOPING.md) 了解更多信息。

## 许可证

这个包裹是 [麻省理工学院的许可](https://npmcn.com/package/LICENSE).

## 常见问题

### @sourceloop/file-utils 是什么？

用于loopback应用程序的文件上传和多部分相关实用程序

### 如何安装 @sourceloop/file-utils？

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

### @sourceloop/file-utils 支持 TypeScript 吗？

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

### @sourceloop/file-utils 支持 ESM 还是 CommonJS？

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

### @sourceloop/file-utils 需要什么版本的 Node\.js？

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

### @sourceloop/file-utils 可以商用吗？

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

### @sourceloop/file-utils 还在维护吗？

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