Multer para JavaScript (Node.js): guia completo com exemplos práticos

1. O que é e para que serve

Multer é uma biblioteca middleware popular para Node.js, projetada para processar dados no formato multipart/form-data — o formato usado no envio de arquivos através de formulários HTML. Diferente do módulo padrão body-parser, que só trabalha com JSON e dados codificados em URL, o Multer consegue interpretar requisições compostas, extrair arquivos e salvá-los no servidor (em memória ou no disco). A biblioteca é construída sobre o módulo busboy e oferece uma API prática para configurar diretórios, nomes de arquivos, filtros de tipo e limites de tamanho.

Para que serve o Multer? Em qualquer aplicação web onde o usuário precise enviar um avatar, documento, imagem ou vídeo, é necessário processar multipart/form-data. O Express.js (o framework mais popular para Node.js) não tem suporte nativo a esse formato, tornando o Multer uma ferramenta essencial. Ele permite que o desenvolvedor foque na lógica de negócio, sem se preocupar com a análise de baixo nível de dados binários.

O Multer suporta o upload de um ou vários arquivos simultaneamente, trabalha com campos de formulário, geração personalizada de nomes de arquivos, filtragem por tipos MIME e extensões, além de limitar o tamanho dos dados enviados. Graças à sua configuração flexível, a biblioteca é adequada tanto para projetos simples (como upload de avatares) quanto para sistemas complexos com armazenamento em nuvem (através de armazenamentos personalizados).

2. Instalação

A instalação é feita via npm (Node Package Manager). Certifique-se de ter o Node.js instalado (versão 12 ou superior).

npm install multer

Após a instalação, a biblioteca estará disponível para importação no seu projeto.

3. Início rápido — exemplo funcional mínimo

Vamos criar um servidor simples com Express.js que recebe o upload de um arquivo via formulário e o salva na pasta uploads/.

Passo 1. Estrutura do projeto

mkdir multer-example
cd multer-example
npm init -y
npm install express multer
touch index.html
touch server.js

Passo 2. Formulário HTML (index.html)

<!DOCTYPE html>
<html lang="pt">
<head>
    <meta charset="UTF-8">
    <title>Upload de Arquivo</title>
</head>
<body>
    <h1>Envie seu arquivo</h1>
    <form action="/upload" method="POST" enctype="multipart/form-data">
        <input type="file" name="myFile" required>
        <button type="submit">Enviar</button>
    </form>
</body>
</html>

Passo 3. Servidor (server.js)

const express = require('express');
const multer = require('multer');
const path = require('path');

const app = express();
const PORT = 3000;

// Configuração do Multer: arquivos serão salvos na pasta 'uploads/'
const storage = multer.diskStorage({
    destination: (req, file, cb) => {
        cb(null, 'uploads/');
    },
    filename: (req, file, cb) => {
        // Gera um nome único: data atual + extensão original
        const uniqueSuffix = Date.now() + '-' + Math.round(Math.random() * 1E9);
        cb(null, uniqueSuffix + path.extname(file.originalname));
    }
});

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

// Servir o HTML estático
app.get('/', (req, res) => {
    res.sendFile(__dirname + '/index.html');
});

// Processar o upload do arquivo
app.post('/upload', upload.single('myFile'), (req, res) => {
    if (!req.file) {
        return res.status(400).send('Nenhum arquivo enviado.');
    }
    res.send(`Arquivo "${req.file.originalname}" enviado com sucesso. Tamanho: ${req.file.size} bytes.`);
});

app.listen(PORT, () => {
    console.log(`Servidor rodando em http://localhost:${PORT}`);
});