# @midwayjs/upload

> Midway Component for upload

Latest version **4.2.6** (published 2026-10-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install @midwayjs/upload
pnpm add @midwayjs/upload
yarn add @midwayjs/upload
bun add @midwayjs/upload
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 4.2.6 |
| Published | 2026-10-18 |
| First published | 2021-12-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=20 |
| Dependencies | 2 |
| Unpacked size | 37.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 7755 |
| Maintainers | czy88840616, legendecas, echosoar, lellansin, lxxyx, stone-jin, mariodu |

## Links

- npm: https://www.npmjs.com/package/@midwayjs/upload
- Repository: https://github.com/midwayjs/midway
- Homepage: https://github.com/midwayjs/midway#readme
- Issues: https://github.com/midwayjs/midway/issues
- npm.io page: https://npm.io/package/@midwayjs/upload

## Dependencies (2)

- [raw-body](https://npm.io/package/raw-body.md) 2.5.2
- [file-type](https://npm.io/package/file-type.md) 21.3.4

## Recent versions

- 4.2.6 (latest) — 2026-10-18
- 4.0.1-beta.1 (beta) — 2026-04-02
- 4.0.0-alpha.1 (alpha) — 2024-12-15
- 4.2.5 — 2026-10-06
- 4.2.4 — 2026-09-27
- 4.2.3 — 2026-09-06
- 4.2.2 — 2026-08-27
- 4.2.1 — 2026-06-14
- 4.1.0 — 2026-05-03
- 3.20.24 — 2026-04-25
- 4.0.3 — 2026-04-12
- 3.20.23 — 2026-04-09
- 4.0.2 — 2026-04-06
- 4.0.1 — 2026-04-05
- 4.0.0 — 2026-03-26
- … 190 more at https://npm.io/package/@midwayjs/upload/versions

## README

## Upload 上传组件

适用于 `@midwayjs/faas` 、`@midwayjs/web` 、`@midwayjs/koa` 和 `@midwayjs/express` 多种框架的通用上传组件，支持 `file` (服务器临时文件)、`stream` （流）多种模式。

### Usage

1. 安装依赖
```shell
tnpm i @midwayjs/upload --save
```
2. 在 configuration 中引入组件,
```ts
import * as upload from '@midwayjs/upload';
@Configuration({
  imports: [
    // ...other components
    upload
  ],
})
export class AutoConfiguration {}
```

3. 在代码中获取上传的文件
```ts
@Controller('/')
export class HomeController {

  @Inject()
  ctx;

  @Post('/upload')
  async upload(@Files() files: upload.UploadFileInfo[], @Fields() fields) {
    /*
    files = [
      {
        filename: 'test.pdf',        // 文件原名
        data: '/var/tmp/xxx.pdf',    // mode 为 file 时为服务器临时文件地址
        fieldName: 'test1',          // 表单 field 名
        mimeType: 'application/pdf', // mime
      },
      {
        filename: 'test.pdf',        // 文件原名
        data: ReadStream,    // mode 为 stream 时为服务器临时文件地址
        fieldName: 'test2',          // 表单 field 名
        mimeType: 'application/pdf', // mime
      },
      // ...file 下支持同时上传多个文件
    ]

    */
    return {
      files,
      fields
    }
  }
}
```


### 配置
```ts
export const upload = {
  // mode: UploadMode, 默认为file，即上传到服务器临时目录，可以配置为 stream
  mode: 'file',
  // fileSize: string, 最大上传文件大小，默认为 10mb
  fileSize: '10mb',
  // whitelist: string[]，文件扩展名白名单，默认为 null
  whitelist: null,
  // tmpdir: string，上传的文件临时存储路径
  tmpdir: join(tmpdir(), 'midway-upload-files'),
  // cleanTimeout: number，上传的文件在临时目录中多久之后自动删除，默认为 5 分钟
  cleanTimeout: 5 * 60 * 1000,
  // base64: boolean，设置原始body是否是base64格式，默认为false，一般用于腾讯云的兼容
  base64: false,
}
```

---
_Source: https://npm.io/package/@midwayjs/upload · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._