• body-parser
• compression
• connect-rid
• cookie-parser
• cookie-session
• cors
• errorhandler
• method-override
• morgan
• multer
• response-time
• serve-favicon
• serve-index
• serve-static
• session
• timeout
• vhost

Multer

Multer は、主にファイルのアップロードに使用される multipart/form-data を処理するための Node.js ミドルウェアです。最大限の効率を得るために busboy の上に構築されています。

注意: Multer は、マルチパート (multipart/form-data) でないフォームは処理しません。

翻訳

この README は他の言語でも利用可能です

• العربية (アラビア語)
• Español (スペイン語)
• 简体中文 (中国語)
• 한국어 (韓国語)
• Русский язык (ロシア語)
• Việt Nam (ベトナム語)
• Português (ブラジルポルトガル語)
• Français (フランス語)
• O’zbek tili (ウズベク語)

インストール

$ npm install --save multer

使用方法

Multer は、`request` オブジェクトに `body` オブジェクトと `file` または `files` オブジェクトを追加します。 `body` オブジェクトにはフォームのテキストフィールドの値が含まれ、`file` または `files` オブジェクトにはフォームを介してアップロードされたファイルが含まれます。

基本的な使用例

フォームで `enctype="multipart/form-data"` を忘れないでください。

<form action="/profile" method="post" enctype="multipart/form-data">
  <input type="file" name="avatar" />
</form>

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 is the `avatar` file
  // req.body will hold the text fields, if there were any
})

app.post('/photos/upload', upload.array('photos', 12), function (req, res, next) {
  // req.files is array of `photos` files
  // req.body will contain the text fields, if there were any
})

const cpUpload = upload.fields([{ name: 'avatar', maxCount: 1 }, { name: 'gallery', maxCount: 8 }])
app.post('/cool-profile', cpUpload, function (req, res, next) {
  // req.files is an object (String -> Array) where fieldname is the key, and the value is array of files
  //
  // e.g.
  //  req.files['avatar'][0] -> File
  //  req.files['gallery'] -> Array
  //
  // req.body will contain the text fields, if there were any
})

テキストのみのマルチパートフォームを処理する必要がある場合は、`.none()` メソッドを使用する必要があります

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 contains the text fields
})

Multer を HTML フォームで使用する例を次に示します。 `enctype="multipart/form-data"` フィールドと `name="uploaded_file"` フィールドに特に注意してください

<form action="/stats" enctype="multipart/form-data" method="post">
  <div class="form-group">
    <input type="file" class="form-control-file" name="uploaded_file">
    <input type="text" class="form-control" placeholder="Number of speakers" name="nspeakers">
    <input type="submit" value="Get me the stats!" class="btn btn-default">
  </div>
</form>

次に、JavaScript ファイルにこれらの行を追加して、ファイルと本文の両方にアクセスします。フォームの `name` フィールド値をアップロード関数で使用することが重要です。これは、リクエストのどのフィールドでファイルを検索する必要があるかを Multer に指示します。これらのフィールドが HTML フォームとサーバーで同じでない場合、アップロードは失敗します

const multer  = require('multer')
const upload = multer({ dest: './public/data/uploads/' })
app.post('/stats', upload.single('uploaded_file'), function (req, res) {
  // req.file is the name of your file in the form above, here 'uploaded_file'
  // req.body will hold the text fields, if there were any 
  console.log(req.file, req.body)
});

API

ファイル情報

各ファイルには、次の情報が含まれています

キー	説明	注記
fieldname	フォームで指定されたフィールド名
originalname	ユーザーのコンピューター上のファイル名
encoding	ファイルのエンコーディングタイプ
mimetype	ファイルの MIME タイプ
size	ファイルのサイズ (バイト単位)
destination	ファイルが保存されたフォルダー	DiskStorage
filename	`destination` 内のファイル名	DiskStorage
path	アップロードされたファイルへのフルパス	DiskStorage
buffer	ファイル全体の `Buffer`	MemoryStorage

multer(opts)

Multer はオプションオブジェクトを受け入れます。最も基本的なものは `dest` プロパティで、Multer にファイルをアップロードする場所を指示します。オプションオブジェクトを省略した場合、ファイルはメモリに保持され、ディスクに書き込まれることはありません。

デフォルトでは、Multer は名前の競合を避けるためにファイルの名前を変更します。名前変更関数は、ニーズに合わせてカスタマイズできます。

Multer に渡すことができるオプションは次のとおりです。

キー	説明
`dest` または `storage`	ファイルを保存する場所
fileFilter	受け入れるファイルを制御する関数
limits	アップロードされたデータの制限
preservePath	ベース名だけでなく、ファイルのフルパスを保持します

平均的な Web アプリでは、`dest` のみが必須であり、次の例に示すように構成されます。

const upload = multer({ dest: 'uploads/' })

アップロードをより詳細に制御する場合は、`dest` の代わりに `storage` オプションを使用する必要があります。 Multer にはストレージエンジン `DiskStorage` と `MemoryStorage` が付属しています。サードパーティからより多くのエンジンが利用可能です。

.single(fieldname)

名前が `fieldname` の単一のファイルを受け入れます。単一のファイルは `req.file` に保存されます。

.array(fieldname[, maxCount])

すべて名前が `fieldname` のファイルの配列を受け入れます。オプションで、`maxCount` 個を超えるファイルがアップロードされた場合にエラーを発生させます。ファイルの配列は `req.files` に保存されます。

.fields(fields)

`fields` で指定されたファイルの組み合わせを受け入れます。ファイルの配列を持つオブジェクトは `req.files` に保存されます。

`fields` は、`name` とオプションで `maxCount` を持つオブジェクトの配列である必要があります。例

[
  { name: 'avatar', maxCount: 1 },
  { name: 'gallery', maxCount: 8 }
]

.none()

テキストフィールドのみを受け入れます。ファイルのアップロードが行われた場合、「LIMIT_UNEXPECTED_FILE」コードのエラーが発生します。

.any()

ネットワーク経由で送信されるすべてのファイルを受け入れます。ファイルの配列は `req.files` に保存されます。

警告: ユーザーがアップロードしたファイルを常に処理してください。悪意のあるユーザーが予期しないルートにファイルをアップロードする可能性があるため、Multer をグローバルミドルウェアとして追加しないでください。アップロードされたファイルを処理しているルートでのみこの関数を使用してください。

storage

DiskStorage

ディスクストレージエンジンを使用すると、ファイルをディスクに保存することを完全に制御できます。

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` の 2 つのオプションがあります。どちらも、ファイルを保存する場所を決定する関数です。

`destination` は、アップロードされたファイルをどのフォルダーに保存するかを決定するために使用されます。これは `string` (例: `'/tmp/uploads'`) として指定することもできます。 `destination` が指定されていない場合、オペレーティングシステムの一時ファイルのデフォルトディレクトリが使用されます。

注: `destination` を関数として提供する場合は、ディレクトリの作成を担当します。文字列を渡すと、multer はディレクトリが作成されることを確認します。

`filename` は、フォルダー内でファイルに付ける名前を決定するために使用されます。 `filename` が指定されていない場合、各ファイルにはファイル拡張子が含まれていないランダムな名前が付けられます。

注: Multer はファイル拡張子を追加しないため、関数はファイル拡張子を含む完全なファイル名を返す必要があります。

各関数には、リクエスト (`req`) とファイルに関する情報 (`file`) の両方が渡され、決定を支援します。

`req.body` はまだ完全に入力されていない可能性があることに注意してください。これは、クライアントがフィールドとファイルをサーバーに送信する順序によって異なります。

コールバックで使用される呼び出し規約 (最初のパラメーターとして null を渡す必要がある) を理解するには、Node.js エラー処理 を参照してください

MemoryStorage

メモリ ストレージ エンジンは、ファイルを `Buffer` オブジェクトとしてメモリに保存します。オプションはありません。

const storage = multer.memoryStorage()
const upload = multer({ storage: storage })

メモリ ストレージを使用する場合、ファイル情報には、ファイル全体を含む `buffer` というフィールドが含まれます。

警告: メモリ ストレージを使用する場合、非常に大きなファイル、または比較的小さなファイルを大量に非常に高速にアップロードすると、アプリケーションのメモリが不足する可能性があります。

limits

次のオプションのプロパティのサイズ制限を指定するオブジェクト。 Multer はこのオブジェクトを busboy に直接渡し、プロパティの詳細は busboy のページ にあります。

次の整数値を使用できます

キー	説明	デフォルト
fieldNameSize	最大フィールド名サイズ	100 バイト
fieldSize	最大フィールド値サイズ (バイト単位)	1MB
fields	ファイル以外のフィールドの最大数	無限
fileSize	マルチパートフォームの場合、最大ファイルサイズ (バイト単位)	無限
files	マルチパートフォームの場合、ファイルフィールドの最大数	無限
parts	マルチパートフォームの場合、パーツ (フィールド + ファイル) の最大数	無限
headerPairs	マルチパートフォームの場合、解析するヘッダー key=>value ペアの最大数	2000

制限を指定すると、サービス拒否 (DoS) 攻撃からサイトを保護するのに役立ちます。

fileFilter

これを関数に設定して、どのファイルをアップロードし、どのファイルをスキップするかを制御します。関数は次のようになります

function fileFilter (req, file, cb) {

  // The function should call `cb` with a boolean
  // to indicate if the file should be accepted

  // To reject this file pass `false`, like so:
  cb(null, false)

  // To accept the file pass `true`, like so:
  cb(null, true)

  // You can always pass an error if something goes wrong:
  cb(new Error('I don\'t have a clue!'))

}

エラー処理

エラーが発生した場合、Multer はエラーを Express に委任します。標準の Express の方法を使用して、適切なエラーページを表示できます。

Multer からのエラーを具体的にキャッチしたい場合は、ミドルウェア関数を自分で呼び出すことができます。また、Multer エラーのみ をキャッチしたい場合は、`multer` オブジェクト自体にアタッチされている `MulterError` クラスを使用できます (例: `err instanceof multer.MulterError`)。

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) {
      // A Multer error occurred when uploading.
    } else if (err) {
      // An unknown error occurred when uploading.
    }

    // Everything went fine.
  })
})

カスタムストレージエンジン

独自のストレージエンジンを構築する方法については、Multer ストレージエンジンを参照してください。

ライセンス

MIT