此文檔於2016年10月3日翻譯時multer的版本是1.2.0，它可能不是最新的！ 甚至可能存在翻譯錯誤！你可能需要閱讀原版英語README 此文檔僅供參考！
Multer
Multer 是一個 node.js 中間件，用於處理 multipart/form-data 類型的表單數據，它主要用於上傳文件。它是寫在 busboy 之上非常高效。
注意: Multer 不會處理任何非 multipart/form-data 類型的表單數據。
其它語言
- English (英語)
- 한국어 (朝鮮語)
- Русский язык (俄語)
安裝
$ npm install --save multer
使用
Multer 會添加一個 body 對象 以及 file 或 files 對象 到 express 的 request 對象中。 body 對象包含表單的文本域信息，file 或 files 對象包含對象表單上傳的文件信息。
基本使用方法:
var express = require('express')
var multer = require('multer')
var upload = multer({ dest: 'uploads/' })
var 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 將具有文本域數據，如果存在的話
})
var cpUpload = upload.fields([{ name: 'avatar', maxCount: 1 }, { name: 'gallery', maxCount: 8 }])
app.post('/cool-profile', cpUpload, function (req, res, next) {
// req.files 是一個對象 (String -> Array) 鍵是文件名，值是文件數組
//
// 例如：
// req.files['avatar'][0] -> File
// req.files['gallery'] -> Array
//
// req.body 將具有文本域數據，如果存在的話
})
如果你需要處理一個只有文本域的表單，你應當使用 .none():
var express = require('express')
var app = express()
var multer = require('multer')
var upload = multer()
app.post('/profile', upload.none(), function (req, res, next) {
// req.body 包含文本域
})
API
文件信息
每個文件具有下面的信息:
| Key | Description | Note |
|---|---|---|
fieldname |
Field name 由表單指定 | |
originalname |
用戶計算機上的文件的名稱 | |
encoding |
文件編碼 | |
mimetype |
文件的 MIME 類型 | |
size |
文件大小（字節單位） | |
destination |
保存路徑 | DiskStorage |
filename |
保存在 destination 中的文件名 |
DiskStorage |
path |
已上傳文件的完整路徑 | DiskStorage |
buffer |
一個存放了整個文件的 Buffer |
MemoryStorage |
multer(opts)
Multer 接受一個 options 對象，其中最基本的是 dest 屬性，這將告訴 Multer 將上傳文件保存在哪。如果你省略 options 對象，這些文件將保存在內存中，永遠不會寫入磁盤。
為了避免命名沖突，Multer 會修改上傳的文件名。這個重命名功能可以根據您的需要定制。
以下是可以傳遞給 Multer 的選項。
| Key | Description |
|---|---|
dest or storage |
在哪里存儲文件 |
fileFilter |
文件過濾器，控制哪些文件可以被接受 |
limits |
限制上傳的數據 |
preservePath |
保存包含文件名的完整文件路徑 |
通常，一般的網頁應用，只需要設置 dest 屬性，像這樣：
var upload = multer({ dest: 'uploads/' })
如果你想在上傳時進行更多的控制，你可以使用 storage 選項替代 dest。Multer 具有 DiskStorage 和 MemoryStorage 兩個存儲引擎；另外還可以從第三方獲得更多可用的引擎。
.single(fieldname)
接受一個以 fieldname 命名的文件。這個文件的信息保存在 req.file。
.array(fieldname[, maxCount])
接受一個以 fieldname 命名的文件數組。可以配置 maxCount 來限制上傳的最大數量。這些文件的信息保存在 req.files。
.fields(fields)
接受指定 fields 的混合文件。這些文件的信息保存在 req.files。
fields 應該是一個對象數組，應該具有 name 和可選的 maxCount 屬性。
Example:
[
{ name: 'avatar', maxCount: 1 },
{ name: 'gallery', maxCount: 8 }
]
.none()
只接受文本域。如果任何文件上傳到這個模式，將發生 "LIMIT_UNEXPECTED_FILE" 錯誤。這和 upload.fields([]) 的效果一樣。
.any()
接受一切上傳的文件。文件數組將保存在 req.files。
警告: 確保你總是處理了用戶的文件上傳。 永遠不要將 multer 作為全局中間件使用，因為惡意用戶可以上傳文件到一個你沒有預料到的路由，應該只在你需要處理上傳文件的路由上使用。
storage
磁盤存儲引擎 (DiskStorage)
磁盤存儲引擎可以讓你控制文件的存儲。
var storage = multer.diskStorage({
destination: function (req, file, cb) {
cb(null, '/tmp/my-uploads')
},
filename: function (req, file, cb) {
cb(null, file.fieldname + '-' + Date.now())
}
})
var upload = multer({ storage: storage })
有兩個選項可用，destination 和 filename。他們都是用來確定文件存儲位置的函數。
destination 是用來確定上傳的文件應該存儲在哪個文件夾中。也可以提供一個 string (例如 '/tmp/uploads')。如果沒有設置 destination，則使用操作系統默認的臨時文件夾。
注意: 如果你提供的 destination 是一個函數，你需要負責創建文件夾。當提供一個字符串，multer 將確保這個文件夾是你創建的。
filename 用於確定文件夾中的文件名的確定。 如果沒有設置 filename，每個文件將設置為一個隨機文件名，並且是沒有擴展名的。
注意: Multer 不會為你添加任何擴展名，你的程序應該返回一個完整的文件名。
每個函數都傳遞了請求對象 (req) 和一些關於這個文件的信息 (file)，有助於你的決定。
注意 req.body 可能還沒有完全填充，這取決於向客戶端發送字段和文件到服務器的順序。
內存存儲引擎 (MemoryStorage)
內存存儲引擎將文件存儲在內存中的 Buffer 對象，它沒有任何選項。
var storage = multer.memoryStorage()
var upload = multer({ storage: storage })
當使用內存存儲引擎，文件信息將包含一個 buffer 字段，里面包含了整個文件數據。
警告: 當你使用內存存儲，上傳非常大的文件，或者非常多的小文件，會導致你的應用程序內存溢出。
limits
一個對象，指定一些數據大小的限制。Multer 通過這個對象使用 busboy，詳細的特性可以在 busboy's page 找到。
可以使用下面這些:
| Key | Description | Default |
|---|---|---|
fieldNameSize |
field 名字最大長度 | 100 bytes |
fieldSize |
field 值的最大長度 | 1MB |
fields |
非文件 field 的最大數量 | 無限 |
fileSize |
在 multipart 表單中，文件最大長度 (字節單位) | 無限 |
files |
在 multipart 表單中，文件最大數量 | 無限 |
parts |
在 multipart 表單中，part 傳輸的最大數量(fields + files) | 無限 |
headerPairs |
在 multipart 表單中，鍵值對最大組數 | 2000 |
設置 limits 可以幫助保護你的站點抵御拒絕服務 (DoS) 攻擊。
fileFilter
設置一個函數來控制什么文件可以上傳以及什么文件應該跳過，這個函數應該看起來像這樣：
function fileFilter (req, file, cb) {
// 這個函數應該調用 `cb` 用boolean值來
// 指示是否應接受該文件
// 拒絕這個文件，使用`false`，像這樣:
cb(null, false)
// 接受這個文件，使用`true`，像這樣:
cb(null, true)
// 如果有問題，你可以總是這樣發送一個錯誤:
cb(new Error('I don\'t have a clue!'))
}
錯誤處理機制
當遇到一個錯誤，multer 將會把錯誤發送給 express。你可以使用一個比較好的錯誤展示頁 (express標准方式)。
如果你想捕捉 multer 發出的錯誤，你可以自己調用中間件程序。如果你想捕捉 Multer 錯誤，你可以使用 multer 對象下的 MulterError 類 (即 err instanceof multer.MulterError)。
var multer = require('multer')
var upload = multer().single('avatar')
app.post('/profile', function (req, res) {
upload(req, res, function (err) {
if (err instanceof multer.MulterError) {
// 發生錯誤
} else if (err) {
// 發生錯誤
}
// 一切都好
})
})
定制存儲引擎
如果你想要構建自己的存儲引擎，請看 這里 。