multer - GitLite

KO | EN

gitlite — search

#python #ai #typescript #machine-learning #rust #macos #windows #awesome #kubernetes #security #openai #ios #mcp #open-source

multer

(★ 12,082)

`multipart/form-data` 처리를 위한 Node.js 미들웨어입니다.

파일 탐색기

최종 버전 다운로드 (.zip)

- - ci.yml
  - codeql.yml
  - scorecard.yml
- dependabot.yml
- README-ar.md
- README-es.md
- README-fr.md
- README-ko.md
- README-pt-br.md
- README-ru.md
- README-tr.md
- README-uz.md
- README-vi.md
- README-zh-cn.md
- counter.js
- file-appender.js
- make-middleware.js
- multer-error.js
- remove-uploaded-files.js
- disk.js
- memory.js
- - empty.dat
  - large.jpg
  - medium.dat
  - small0.dat
  - small1.dat
  - tiny0.dat
  - tiny1.dat
- _util.js
- async-file-filter-orphan.js
- def-param-charset.js
- disk-storage.js
- error-handling.js
- expected-files.js
- express-integration.js
- fields.js
- file-filter.js
- file-ordering.js
- functionality.js
- issue-232.js
- memory-storage.js
- nesting-depth.js
- none.js
- orphan-file-cleanup.js
- reuse-middleware.js
- select-field.js
- unicode.js
.gitignore
.npmrc
CHANGELOG.md
index.js
LICENSE
package.json
README.md
StorageEngine.md

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Multer [![NPM Version][npm-version-image]][npm-url] [![NPM Downloads][npm-downloads-image]][npm-url] [![Build Status][ci-image]][ci-url] [![Test Coverage][test-image]][test-url] [![OpenSSF Scorecard Badge][ossf-scorecard-badge]][ossf-scorecard-visualizer]
Multer는 `multipart/form-data` 처리를 위한 node.js 미들웨어로, 주로 파일 업로드에 사용됩니다. 최고 효율을 위해 [busboy](https://github.com/mscdex/busboy)를 기반으로 작성되었습니다.
\*\*참고\*\*: Multer는 multipart 형식이 아닌(`multipart/form-data`) 폼은 처리하지 않습니다.
## 번역
이 README는 다른 언어로도 제공됩니다:
| | |
| ------------------------------------------------------------------------------ | --------------- |
| [العربية](https://github.com/expressjs/multer/blob/main/doc/README-ar.md) | Arabic |
| [简体中文](https://github.com/expressjs/multer/blob/main/doc/README-zh-cn.md) | Chinese |
| [Français](https://github.com/expressjs/multer/blob/main/doc/README-fr.md) | French |
| [한국어](https://github.com/expressjs/multer/blob/main/doc/README-ko.md) | Korean |
| [Português](https://github.com/expressjs/multer/blob/main/doc/README-pt-br.md) | Portuguese (BR) |
| [Русский язык](https://github.com/expressjs/multer/blob/main/doc/README-ru.md) | Russian |
| [Español](https://github.com/expressjs/multer/blob/main/doc/README-es.md) | Spanish |
| [O'zbek tili](https://github.com/expressjs/multer/blob/main/doc/README-uz.md) | Uzbek |
| [Việt Nam](https://github.com/expressjs/multer/blob/main/doc/README-vi.md) | Vietnamese |
| [Türkçe](https://github.com/expressjs/multer/blob/main/doc/README-tr.md) | Turkish |
## 설치
```sh
$ npm install multer
```
## 사용법
Multer는 `request` 객체에 `body` 객체와 `file` 또는 `files` 객체를 추가합니다. `body` 객체에는 폼의 텍스트 필드 값이 포함되며, `file` 또는 `files` 객체에는 폼을 통해 업로드된 파일이 포함됩니다.
기본 사용법 예시:
폼에 `enctype="multipart/form-data"`를 추가하는 것을 잊지 마세요.
```html

```javascript
const express = require('express')
const multer = require('multer')
const upload = multer({ dest: 'uploads/' })
const app = express()
app.post('/profile', upload.single('avatar'), function (req, res, next) {
// req.file은 `avatar` 파일입니다.
// req.body에는 텍스트 필드가 있는 경우 해당 필드가 포함됩니다.
})
app.post('/photos/upload', upload.array('photos', 12), function (req, res, next) {
// req.files는 `photos` 파일들의 배열입니다.
// req.body에는 텍스트 필드가 있는 경우 해당 필드가 포함됩니다.
})
const uploadMiddleware = upload.fields([{ name: 'avatar', maxCount: 1 }, { name: 'gallery', maxCount: 8 }])
app.post('/cool-profile', uploadMiddleware, function (req, res, next) {
// req.files는 객체(String -> Array)이며, 필드명이 키이고 값이 파일 배열입니다.
//
// 예:
// req.files['avatar'][0] -> 파일
// req.files['gallery'] -> 배열
//
// req.body에는 텍스트 필드가 있는 경우 해당 필드가 포함됩니다.
})
```
텍스트 전용 multipart 폼을 처리해야 하는 경우, `.none()` 메서드를 사용해야 합니다:
```javascript
const express = require('express')
const app = express()
const multer = require('multer')
const upload = multer()
app.post('/profile', upload.none(), function (req, res, next) {
// req.body에는 텍스트 필드들이 포함됩니다.
})
```
HTML 폼에서 Multer가 어떻게 사용되는지 보여주는 예시입니다. `enctype="multipart/form-data"`와 `name="uploaded\_file"` 필드에 특히 주의하세요:
```html
```
그런 다음 자바스크립트 파일에서 파일과 본문 모두에 접근하기 위해 다음 줄들을 추가합니다. 업로드 함수에서 폼의 `name` 필드 값을 사용하는 것이 중요합니다. 이는 Multer에게 요청의 어떤 필드에서 파일을 찾아야 하는지 알려줍니다. HTML 폼과 서버의 이 필드들이 일치하지 않으면 업로드가 실패합니다:
```javascript
const multer = require('multer')
const upload = multer({ dest: './public/data/uploads/' })
app.post('/stats', upload.single('uploaded\_file'), function (req, res) {
// req.file은 위 폼에서의 파일 이름이며, 여기서는 'uploaded\_file'입니다.
// req.body에는 텍스트 필드가 있는 경우 해당 필드가 포함됩니다.
console.log(req.file, req.body)
});
```
## API
### 파일 정보
각 파일은 다음 정보를 포함합니다:
Key | Description | Note
--- | --- | ---
`fieldname` | 폼에 지정된 필드 이름 |
`originalname` | 사용자의 컴퓨터에 있는 파일 이름 |
`encoding` | 파일의 인코딩 타입 |
`mimetype` | 파일의 Mime 타입 |
`size` | 바이트 단위의 파일 크기 |
`destination` | 파일이 저장된 폴더 | `DiskStorage`
`filename` | `destination` 내에서의 파일 이름 | `DiskStorage`
`path` | 업로드된 파일의 전체 경로 | `DiskStorage`
`buffer` | 전체 파일의 `Buffer` | `MemoryStorage`
### `multer(opts)`
Multer는 옵션 객체를 받으며, 가장 기본적인 것은 Multer가 파일을 업로드할 위치를 지정하는 `dest` 속성입니다. 옵션 객체를 생략하면 파일은 메모리에 유지되며 디스크에 기록되지 않습니다.
기본적으로 Multer는 이름 충돌을 방지하기 위해 파일 이름을 변경합니다. 이름 변경 함수는 사용자의 필요에 따라 커스터마이징할 수 있습니다.
다음은 Multer에 전달할 수 있는 옵션들입니다.
Key | Description
--- | ---
`dest` or `storage` | 파일을 저장할 위치
`fileFilter` | 허용할 파일을 제어하는 함수
`limits` | 업로드된 데이터의 제한
`preservePath` | 기본 이름만 사용하는 대신 파일의 전체 경로 유지
`defParamCharset` | 확장된 파라미터(명시적 문자셋을 포함하는)가 아닌 파트 헤더 파라미터(예: filename)의 값에 사용할 기본 문자셋. 기본값: `'latin1'`
일반적인 웹 앱에서는 `dest`만 필요할 수 있으며, 다음 예시와 같이 설정합니다.
```javascript
const upload = multer({ dest: 'uploads/' })
```
업로드에 대한 더 많은 제어권을 원한다면, `dest` 대신 `storage` 옵션을 사용하고 싶을 것입니다. Multer는 스토리지 엔진으로 `DiskStorage`와 `MemoryStorage`를 기본 제공하며, 더 많은 엔진을 thir
```

제3자.
#### `.single(fieldname)`
`fieldname` 이름을 가진 단일 파일을 허용합니다. 단일 파일은 `req.file`에 저장됩니다.
#### `.array(fieldname[, maxCount])`
모두 `fieldname` 이름을 가진 파일들의 배열을 허용합니다. 선택적으로 `maxCount`보다 많은 파일이 업로드되면 에러를 발생시킵니다. 파일 배열은 `req.files`에 저장됩니다.
#### `.fields(fields)`
`fields`로 지정된 혼합된 파일들을 허용합니다. 파일 배열들을 포함하는 객체가 `req.files`에 저장됩니다.
`fields`는 `name`과 선택적으로 `maxCount`를 포함하는 객체들의 배열이어야 합니다.
예시:
```javascript
[
{ name: 'avatar', maxCount: 1 },
{ name: 'gallery', maxCount: 8 }
]
```
#### `.none()`
텍스트 필드만 허용합니다. 파일 업로드가 발생하면 "LIMIT\\_UNEXPECTED\\_FILE" 코드로 에러가 발생합니다.
#### `.any()`
전송되는 모든 파일을 허용합니다. 파일 배열이 `req.files`에 저장됩니다.
\*\*경고:\*\* 사용자가 업로드한 파일을 항상 처리하도록 하세요. 악의적인 사용자가 예상치 못한 라우트에 파일을 업로드할 수 있으므로 multer를 전역 미들웨어로 절대 추가하지 마세요. 업로드된 파일을 처리하는 라우트에서만 이 함수를 사용하세요.
### `storage`
#### `DiskStorage`
디스크 스토리지 엔진은 디스크에 파일을 저장하는 것에 대한 완전한 제어권을 제공합니다.
```javascript
const storage = multer.diskStorage({
destination: function (req, file, cb) {
cb(null, '/tmp/my-uploads')
},
filename: function (req, file, cb) {
const uniqueSuffix = Date.now() + '-' + Math.round(Math.random() \* 1E9)
cb(null, file.fieldname + '-' + uniqueSuffix)
}
})
const upload = multer({ storage: storage })
```
`destination`과 `filename`의 두 가지 옵션을 사용할 수 있습니다. 둘 다 파일이 저장되어야 할 위치를 결정하는 함수입니다.
`destination`은 업로드된 파일이 저장될 폴더를 결정하는 데 사용됩니다. 이는 `string`(예: `'/tmp/uploads'`)으로 지정할 수도 있습니다. `destination`이 지정되지 않은 경우, 운영 체제의 임시 파일 기본 디렉터리가 사용됩니다.
\*\*참고:\*\* `destination`을 함수로 제공할 때는 디렉터리를 직접 생성할 책임이 있습니다. 문자열을 전달하는 경우, multer가 디렉터리가 생성되도록 보장합니다.
`filename`은 폴더 내에서 파일의 이름을 결정하는 데 사용됩니다. `filename`이 지정되지 않으면, 각 파일에는 파일 확장자가 포함되지 않은 임의의 이름이 지정됩니다.
\*\*참고:\*\* Multer는 파일 확장자를 자동으로 추가해주지 않으며, 함수는 파일 확장자가 포함된 완전한 파일 이름을 반환해야 합니다.
각 함수에는 결정에 도움을 주기 위해 요청 객체(`req`)와 파일에 대한 일부 정보(`file`)가 모두 전달됩니다.
`req.body`가 아직 완전히 채워지지 않았을 수 있으니 참고하세요. 이는 클라이언트가 필드와 파일을 서버로 전송하는 순서에 따라 다릅니다.
콜백에서 사용되는 호출 컨벤션(첫 번째 파라미터로 null을 전달해야 하는 것)을 이해하려면 다음을 참고하세요.
[Node.js error handling](https://web.archive.org/web/20220417042018/https://www.joyent.com/node-js/production/design/errors)
#### `MemoryStorage`
메모리 스토리지 엔진은 파일을 `Buffer` 객체로 메모리에 저장합니다. 어떠한 옵션도 가지고 있지 않습니다.
```javascript
const storage = multer.memoryStorage()
const upload = multer({ storage: storage })
```
메모리 스토리지를 사용할 때, 파일 정보에는 전체 파일을 포함하는 `buffer`라는 필드가 포함됩니다.
\*\*경고\*\*: 메모리 스토리지를 사용할 때 매우 큰 파일이나, 비교적 작은 파일들을 매우 빠른 속도로 대량 업로드하면 애플리케이션의 메모리가 부족해질 수 있습니다.
### `limits`
다음 선택적 속성들의 크기 제한을 지정하는 객체입니다. Multer는 이 객체를 busboy에 직접 전달하며, 속성에 대한 세부 정보는 [busboy's page](https://github.com/mscdex/busboy#exports)에서 확인할 수 있습니다.
다음과 같은 정수 값들을 사용할 수 있습니다:
Key | Description | Default
--- | --- | ---
`fieldNameSize` | Max field name size | 100 bytes
`fieldSize` | Max field value size (in bytes) | 1MB
`fields` | Max number of non-file fields | Infin

ity
`fileSize` | 멀티파트 폼의 경우, 최대 파일 크기 (바이트 단위) | Infinity
`files` | 멀티파트 폼의 경우, 최대 파일 필드 개수 | Infinity
`parts` | 멀티파트 폼의 경우, 파트의 최대 개수 (필드 + 파일) | Infinity
`headerPairs` | 멀티파트 폼의 경우, 파싱할 헤더 key=>value 쌍의 최대 개수 | 2000
`fieldNestingDepth` | 필드 이름의 최대 중첩 수준 (예: `a[b][c]`는 2수준을 가짐) | Infinity
제한을 지정하면 서비스 거부(DoS) 공격으로부터 사이트를 보호하는 데 도움이 될 수 있습니다.
### `fileFilter`
어떤 파일을 업로드하고 어떤 파일을 건너뛸지 제어하려면 이 옵션을 함수로 설정하세요. 함수는 다음과 같아야 합니다:
```javascript
function fileFilter (req, file, cb) {
// 함수는 파일 수락 여부를 나타내기 위해
// 부울 값과 함께 `cb`를 호출해야 합니다.
// 파일을 거부하려면 다음과 같이 `false`를 전달하세요:
cb(null, false)
// 파일을 수락하려면 다음과 같이 `true`를 전달하세요:
cb(null, true)
// 문제가 발생하면 언제든지 에러를 전달할 수 있습니다:
cb(new Error('I don\'t have a clue!'))
}
```
## 보안
[limits](#limits)를 지정하면 서비스 거부(DoS) 공격으로부터 사이트를 보호하는 데 도움이 될 수 있습니다. 대부분의 애플리케이션에서는 다음과 같은 제한을 권장합니다:
- `fileSize` -- 사용 사례에 맞는 예상 최대 파일 크기로 설정
- `files` -- 요청당 최대 파일 개수로 설정
- `fields` -- 요청당 최대 텍스트 필드 개수로 설정
- `fieldNestingDepth` -- 필드 이름에 필요한 최소 깊이로 설정 (예: `a[b][c]`의 경우 `3`)
## 에러 처리
에러가 발생하면 Multer는 Express에 에러를 위임합니다. [표준 Express 방식](https://expressjs.com/en/guide/error-handling/)을 사용하여 보기 좋은 에러 페이지를 표시할 수 있습니다.
Multer에서 발생하는 에러만 특별히 잡고 싶다면, 미들웨어 함수를 직접 호출하면 됩니다. 또한 [Multer 에러](https://github.com/expressjs/multer/blob/main/lib/multer-error.js)만 잡고 싶다면, `multer` 객체 자체에 연결된 `MulterError` 클래스를 사용할 수 있습니다 (예: `err instanceof multer.MulterError`).
```javascript
const multer = require('multer')
const upload = multer().single('avatar')
app.post('/profile', function (req, res) {
upload(req, res, function (err) {
if (err instanceof multer.MulterError) {
// 업로드 중 Multer 에러가 발생했습니다.
} else if (err) {
// 업로드 중 알 수 없는 에러가 발생했습니다.
}
// 모든 것이 정상적으로 처리되었습니다.
})
})
```
## 커스텀 스토리지 엔진
나만의 스토리지 엔진을 구축하는 방법에 대한 정보는 [Multer Storage Engine](https://github.com/expressjs/multer/blob/main/StorageEngine.md)을 참조하세요.
## 라이선스
[MIT](LICENSE)
[ci-image]: https://github.com/expressjs/multer/actions/workflows/ci.yml/badge.svg
[ci-url]: https://github.com/expressjs/multer/actions/workflows/ci.yml
[test-url]: https://coveralls.io/r/expressjs/multer?branch=main
[test-image]: https://badgen.net/coveralls/c/github/expressjs/multer/main
[npm-downloads-image]: https://badgen.net/npm/dm/multer
[npm-url]: https://npmjs.org/package/multer
[npm-version-image]: https://badgen.net/npm/v/multer
[ossf-scorecard-badge]: https://api.scorecard.dev/projects/github.com/expressjs/multer/badge
[ossf-scorecard-visualizer]: https://ossf.github.io/scorecard-visualizer/#/projects/github.com/expressjs/multer