multer middleware

Multer は multipart/form-data を扱うための node.js ミドルウェアで、主にファイルのアップロードに使用されます。 の上に busboyと書かれており、最大限の効率を得ることができます。

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

翻訳

このREADMEは他の言語でも利用できます:

インストール

$ npm install multer

使用法

Multer は body オブジェクトと file または files オブジェクトを request オブジェクトに追加します。 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 uploadMiddleware = upload.fields([
  { name: 'avatar', maxCount: 1 },
  { name: 'gallery', maxCount: 8 },
]);
app.post('/cool-profile', uploadMiddleware, 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

ファイル情報

各ファイルには以下の情報が含まれています:

multer(opts)

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

デフォルトでは、Multer は名前の衝突を避けるためにファイルの名前を変更します。 の名前変更機能は、必要に応じてカスタマイズできます。

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

In an average web app, only dest might be required, and configured as shown in the following example.

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 is used to determine within which folder the uploaded files should be stored. これは文字列として与えることもできます(例: '/tmp/uploads)。 destination が指定されていない場合は、一時的な ファイルのオペレーティングシステムのデフォルトディレクトリが使用されます。

注意: 関数として destination を指定するときにディレクトリを作成します。 文字列を渡すとき、multer は ディレクトリが作成されていることを確認します。

フォルダ内のファイル名を指定するには、filename を使用します。 If no filename is given, each file will be given a random name that doesn’t include any file extension.

注意: Multer はファイル拡張子を追加しません。あなたの関数 はファイル拡張子の完全なファイル名を返します。

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

req.body はまだ完全に入力されていない可能性があります。 これは、クライアントがフィールドとファイルをサーバーに送信する オーダーに依存します。

コールバックで使用される呼び出し規約(最初のパラメータとして null を渡す必要がある)を理解するには、 [Node] を参照してください。 s error handling](https://web.archive.org/web/20220417042018/https://www.joyent.com/node-js/production/design/errors)

MemoryStorage

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

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

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

WARNING: Uploading very large files, or relatively small files in large numbers very quickly, can cause your application to run out of memory when memory storage is used.

limits

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

次の整数値が使用できます。

制限を指定することは、サービス妨害(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に委任します。 You can display a nice error page using the standard express way.

Multer から特にエラーをキャッチしたい場合は、独自に ミドルウェア関数を呼び出すことができます。 Also, if you want to catch only the Multer errors, you can use the MulterError class that is attached to the multer object itself (e.g. 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 Storage Engineを参照してください。

ライセンス

MIT