middleware multer

Multer es un middleware de node.js para manejar multipart/form-data, que se utiliza principalmente para subir archivos. Está escrito encima de busboy para máxima eficiencia.

NOTA: Multer no procesará ninguna forma que no sea multiparte (multipart/form-data).

Traducciones

Este README también está disponible en otros idiomas:

Instalación

$ npm install multer

Uso

Multer añade un objeto body y un objeto file o files al objeto request. El objeto body contiene los valores de los campos de texto del formulario, el objeto file o files contiene los archivos subidos a través del formulario.

Ejemplo de uso básico:

No olvides el enctype="multipart/form-data" en tu formulario.

<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
});

En caso de que necesite manejar un formulario multiparte de solo texto, debe utilizar el método .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
});

Aquí hay un ejemplo de cómo multer se utiliza en un formulario HTML. Toma nota especial de los campos enctype="multipart/form-data" y 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>

Entonces en su archivo javascript usted añadiría estas líneas para acceder tanto al archivo como al cuerpo. Es importante que utilices el valor del campo name del formulario en tu función de subida. Esto le dice a multer en qué campo en la solicitud debe buscar los archivos. Si estos campos no son los mismos en el formulario HTML y en tu servidor, tu subida fallará:

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

Información del archivo

Cada archivo contiene la siguiente información:

multer(opts)

Multer acepta un objeto de opciones, el más básico de los cuales es la propiedad ‘dest’ , que le dice a Multer dónde subir los archivos. En caso de omitir el objeto opciones, los archivos se mantendrán en la memoria y nunca se escribirán en el disco.

Por defecto, Multer renombrará los archivos para evitar conflictos de nombres. La función de renombramiento puede personalizarse según sus necesidades.

Las siguientes son las opciones que se pueden pasar a Multer.

En una aplicación web promedio, sólo dest puede ser requerido, y configurado como se muestra en el siguiente ejemplo.

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

Si quieres más control sobre tus subidas, querrás usar la opción storage en lugar de dest. Múltiples naves con motores de almacenamiento DiskStorage y MemoryStorage; Hay más motores disponibles de terceros.

.single(nombredecampo)

Acepta un solo archivo con el nombre fieldname. El archivo único se almacenará en req.file.

.array(nombredecampo [, maxCount])

Acepta una matriz de archivos, todo con el nombre fieldname. Opcionalmente un error si más de archivos maxCount son subidos. El array de archivos se almacenará en req.files.

.fields(campos)

Acepta una mezcla de archivos, especificada por fields. Un objeto con arrays de archivos será almacenado en req.files.

fields debe ser una matriz de objetos con name y opcionalmente un maxCount. Ejemplo:

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

.None ()

Aceptar sólo campos de texto. Si se realiza cualquier carga de archivos, se emitirá un error con el código “LIMIT_UNEXPECTED_FILE”.

.any()

Acepta todos los archivos que pasan por el cable. Un array de archivos se almacenará en req.files.

ADVERTENCIA: Asegúrate de que siempre gestionas los archivos que sube un usuario. Never add multer as a global middleware since a malicious user could upload files to a route that you didn’t anticipate. Utilice esta función solo en las rutas donde esté manejando los archivos cargados.

almacenamiento

DiskStorage

El motor de almacenamiento de disco le da un control total sobre el almacenamiento de archivos en disco.

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 });

Hay dos opciones disponibles, destination y filename. Son ambas funciones que determinan dónde debe almacenarse el archivo.

destination se utiliza para determinar dentro de qué carpeta deben guardarse los archivos subidos . Esto también se puede dar como una cadena (por ejemplo, '/tmp/uploads'). Si no se da destino, se utiliza el directorio predeterminado del sistema operativo para archivos temporales .

Note: You are responsible for creating the directory when providing destination as a function. Al pasar una cadena, multer se asegurará de que el directorio sea creado para ti.

filename se utiliza para determinar que archivo debe ser nombrado dentro de la carpeta. If no filename is given, each file will be given a random name that doesn’t include any file extension.

Nota: Multer no añadirá ninguna extensión de archivo para ti, tu función debe devolver un nombre de archivo completo con una extensión de archivo.

Cada función pasa tanto la solicitud (req) como alguna información sobre el archivo (file) para ayudar con la decisión.

Tenga en cuenta que req.body podría no haber sido poblado por completo aún. Depende del orden que el cliente transmite campos y archivos al servidor.

Para entender la convención de llamada utilizada en el callback (necesidad de pasar null como primer parámetro), consulte Nodo. s gestión de errores

MemoriaStorage

El motor de almacenamiento de memoria almacena los archivos en memoria como objetos Buffer. no tiene ninguna opción.

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

Al usar almacenamiento de memoria, la información del archivo contendrá un campo llamado buffer que contiene el archivo completo.

ADVERTENCIA: Subir archivos muy grandes, o archivos relativamente pequeños en números grandes muy rápidamente, puede causar que la aplicación se quede sin memoria cuando se utiliza de almacenamiento de memoria.

limites

Un objeto que especifica los límites de tamaño de las siguientes propiedades opcionales. Multer pasa este objeto directamente a busboy, y los detalles de las propiedades se pueden encontrar en la página de busbo.

Los siguientes valores enteros están disponibles:

Especificar los límites puede ayudar a proteger su sitio contra ataques de denegación de servicio (DoS).

fileFilter

Establezca esto en una función para controlar qué archivos deben ser subidos y qué debe ser omitido. La función debe verse así:

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!"));
}

Manejo de errores

Cuando se encuentra un error, Multer delegará el error a Express. You can display a nice error page using the standard express way.

Si quieres capturar errores específicamente desde Multer, puedes llamar a la función de Middleware por ti mismo. También, si quieres atrapar sólo los errores de Multer, puedes usar la clase MulterError que está adjunta al objeto multer en sí mismo (e. . 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.
  });
});

Motor de almacenamiento personalizado

Para obtener información sobre cómo construir tu propio motor de almacenamiento, consulta Motor de almacenamiento múltiple.

Licencia

MIT