Express.js + Multer: загрузка файлов
2025-07-27

Express.js + Multer: загрузка файлов

Multer — это middleware для Express.js, который позволяет обрабатывать multipart/form-data, что необходимо для загрузки файлов. В этой статье рассмотрим, как настроить загрузку файлов, обрабатывать различные типы файлов, валидировать их и обеспечивать безопасность при работе с пользовательскими файлами.

Введение

Загрузка файлов — одна из самых распространённых задач в веб-разработке. Пользователи загружают изображения, документы, видео и другие типы файлов. Express.js по умолчанию не может обрабатывать multipart/form-data, поэтому для этого используют специальные middleware, такие как Multer.

Multer добавляет объект file или files к объекту request, содержащий информацию о загруженных файлах. Это позволяет легко получать доступ к файлам, их именам, размерам и другим метаданным.

1. Установка зависимостей

Для начала установим необходимые пакеты:

npm install express multer
  • express — основной фреймворк для создания API
  • multer — middleware для обработки multipart/form-data и загрузки файлов

2. Базовая настройка Multer

Для начала работы с Multer нужно правильно настроить конфигурацию. Основные компоненты, которые нам понадобятся — это хранилище файлов, фильтр для проверки типов файлов и ограничения на размер.

Хранилище файлов определяет, где и как будут сохраняться загруженные файлы. Multer поддерживает два типа хранилища: сохранение на диск (diskStorage) и сохранение в памяти (memoryStorage). Для большинства случаев лучше использовать сохранение на диск, так как это более эффективно для больших файлов.

Фильтр файлов позволяет проверять тип файла перед его сохранением. Это важная функция безопасности, которая предотвращает загрузку потенциально опасных файлов.

Ограничения помогают контролировать размер файлов и количество одновременно загружаемых файлов, что защищает сервер от перегрузки.

Вот базовая настройка:

const storage = multer.diskStorage({
  destination: function (req, file, cb) {
    cb(null, './uploads');
  },
  filename: function (req, file, cb) {
    const uniqueSuffix = Date.now() + '-' + Math.round(Math.random() * 1E9);
    cb(null, file.fieldname + '-' + uniqueSuffix + path.extname(file.originalname));
  }
});

const fileFilter = (req, file, cb) => {
  const allowedTypes = ['image/jpeg', 'image/png', 'image/gif', 'application/pdf'];

  if (allowedTypes.includes(file.mimetype)) {
    cb(null, true);
  } else {
    cb(new Error('Неподдерживаемый тип файла'), false);
  }
};

const upload = multer({ 
  storage: storage,
  fileFilter: fileFilter,
  limits: {
    fileSize: 5 * 1024 * 1024 // 5MB
  }
});

Ключевые моменты конфигурации:

  • destination — функция, которая определяет папку для сохранения. В нашем случае все файлы сохраняются в папку ./uploads
  • filename — функция для генерации имени файла. Мы создаём уникальное имя, добавляя временную метку и случайное число, чтобы избежать конфликтов имён
  • fileFilter — проверяет MIME-тип файла. Мы разрешаем только изображения и PDF-документы
  • limits.fileSize — ограничивает размер файла до 5 мегабайт

3. Загрузка одного файла

Самый простой случай — загрузка одного файла. Для этого используется метод upload.single(), который принимает имя поля формы, содержащего файл. Multer автоматически обрабатывает загруженный файл и добавляет информацию о нём в объект req.file.

Важные моменты при загрузке одного файла:

  • Проверка наличия файла — всегда проверяйте, что файл действительно был загружен
  • Обработка ошибок — используйте try-catch для перехвата возможных ошибок
  • Информация о файле — Multer предоставляет подробную информацию о загруженном файле

Вот пример маршрута для загрузки одного файла:

app.post('/upload-single', upload.single('file'), (req, res) => {
  try {
    if (!req.file) {
      return res.status(400).json({ error: 'Файл не был загружен' });
    }

    res.json({
      message: 'Файл успешно загружен',
      file: {
        originalname: req.file.originalname,
        filename: req.file.filename,
        mimetype: req.file.mimetype,
        size: req.file.size
      }
    });
  } catch (error) {
    res.status(500).json({ error: 'Ошибка при загрузке файла' });
  }
});

Объект req.file содержит:

  • originalname — оригинальное имя файла на компьютере пользователя
  • filename — имя файла, под которым он сохранён на сервере
  • mimetype — MIME-тип файла (например, image/jpeg)
  • size — размер файла в байтах
  • path — полный путь к файлу на сервере

Для тестирования загрузки файлов можно использовать простую HTML-форму с атрибутом enctype="multipart/form-data", который обязателен для загрузки файлов.

4. Загрузка нескольких файлов

Часто возникает необходимость загрузить несколько файлов одновременно. Для этого используется метод upload.array(), который принимает имя поля формы и максимальное количество файлов. Multer обрабатывает все файлы и добавляет информацию о них в массив req.files.

Особенности множественной загрузки:

  • Ограничение количества — можно установить максимальное количество файлов для предотвращения перегрузки сервера
  • Обработка массива — все файлы доступны в массиве req.files
  • Валидация каждого файла — каждый файл проходит через настроенный фильтр

Вот пример маршрута для загрузки нескольких файлов:

app.post('/upload-multiple', upload.array('files', 5), (req, res) => {
  try {
    if (!req.files || req.files.length === 0) {
      return res.status(400).json({ error: 'Файлы не были загружены' });
    }

    const uploadedFiles = req.files.map(file => ({
      originalname: file.originalname,
      filename: file.filename,
      mimetype: file.mimetype,
      size: file.size
    }));

    res.json({
      message: `${req.files.length} файлов успешно загружено`,
      files: uploadedFiles
    });
  } catch (error) {
    res.status(500).json({ error: 'Ошибка при загрузке файлов' });
  }
});

Ключевые отличия от загрузки одного файла:

  • Используется upload.array('files', 5) вместо upload.single('file')
  • Проверяется req.files (массив) вместо req.file (объект)
  • Обрабатывается массив файлов с помощью map()
  • Второй параметр 5 ограничивает количество файлов до пяти

В HTML-форме для множественной загрузки нужно добавить атрибут multiple к полю ввода файла.

5. Загрузка файлов с дополнительными полями

В реальных приложениях часто требуется загружать файлы вместе с дополнительными данными формы — заголовками, описаниями, категориями и другими метаданными. Multer автоматически обрабатывает как файлы, так и текстовые поля формы.

Как это работает:

Когда пользователь отправляет форму с файлами и текстовыми полями, Multer:

  1. Обрабатывает файлы согласно настройкам
  2. Добавляет файлы в req.file или req.files
  3. Добавляет текстовые поля в req.body

Это позволяет получить доступ ко всем данным формы в одном обработчике.

Вот пример маршрута для загрузки файла с дополнительными данными:

app.post('/upload-with-data', upload.single('file'), (req, res) => {
  try {
    if (!req.file) {
      return res.status(400).json({ error: 'Файл не был загружен' });
    }

    const { title, description, category } = req.body;

    res.json({
      message: 'Файл и данные успешно загружены',
      file: {
        originalname: req.file.originalname,
        filename: req.file.filename,
        mimetype: req.file.mimetype,
        size: req.file.size
      },
      formData: { title, description, category }
    });
  } catch (error) {
    res.status(500).json({ error: 'Ошибка при загрузке' });
  }
});

Важные моменты:

  • Текстовые поля доступны в req.body как обычно
  • Файлы доступны в req.file (один файл) или req.files (несколько файлов)
  • Валидация должна проверять как файлы, так и текстовые данные
  • Сохранение в базу данных — часто нужно сохранить информацию о файле вместе с метаданными

Этот подход особенно полезен для создания галерей изображений, загрузки документов с описаниями или создания профилей пользователей с аватарами.

6. Валидация файлов

Валидация файлов — критически важный аспект безопасности при загрузке файлов. Без правильной валидации злоумышленники могут загружать вредоносные файлы, что может привести к компрометации сервера.

Основные принципы валидации:

  1. Проверка MIME-типа — убеждаемся, что файл действительно имеет заявленный тип
  2. Проверка расширения — проверяем соответствие расширения файла его типу
  3. Ограничение размера — предотвращаем загрузку слишком больших файлов
  4. Белый список — разрешаем только определённые типы файлов

Почему важна двойная проверка:

MIME-тип можно легко подделать, поэтому важно проверять не только его, но и расширение файла. Это создаёт дополнительный уровень защиты.

Вот пример расширенной валидации:

const validateFile = (req, file, cb) => {
  const allowedMimeTypes = {
    'image/jpeg': '.jpg',
    'image/png': '.png',
    'image/gif': '.gif',
    'application/pdf': '.pdf',
    'text/plain': '.txt'
  };

  if (!allowedMimeTypes[file.mimetype]) {
    return cb(new Error('Неподдерживаемый тип файла'), false);
  }

  const fileExtension = path.extname(file.originalname).toLowerCase();
  const expectedExtension = allowedMimeTypes[file.mimetype];

  if (fileExtension !== expectedExtension) {
    return cb(new Error('Расширение файла не соответствует типу'), false);
  }

  cb(null, true);
};

Ключевые аспекты валидации:

  • Белый список типов — мы определяем только разрешённые MIME-типы
  • Соответствие расширения — проверяем, что расширение файла соответствует его типу
  • Информативные ошибки — возвращаем понятные сообщения об ошибках
  • Безопасность по умолчанию — отклоняем файл при любых сомнениях

Такой подход валидации значительно снижает риски безопасности при загрузке файлов.

7. Обработка ошибок

Правильная обработка ошибок — важная часть любого приложения. Multer генерирует специфические ошибки, которые нужно обрабатывать отдельно от обычных ошибок Express.js.

Типы ошибок Multer:

  1. MulterError — специальные ошибки Multer с кодами
  2. Ошибки валидации — ошибки, возвращённые функцией fileFilter
  3. Системные ошибки — ошибки файловой системы или сети

Основные коды ошибок Multer:

  • LIMIT_FILE_SIZE — файл превышает максимальный размер
  • LIMIT_FILE_COUNT — превышено максимальное количество файлов
  • LIMIT_UNEXPECTED_FILE — неожиданное поле файла в форме
  • LIMIT_FIELD_KEY — слишком длинное имя поля
  • LIMIT_FIELD_VALUE — слишком длинное значение поля

Вот пример middleware для обработки ошибок Multer:

app.use((error, req, res, next) => {
  if (error instanceof multer.MulterError) {
    if (error.code === 'LIMIT_FILE_SIZE') {
      return res.status(400).json({
        error: 'Файл слишком большой. Максимальный размер: 5MB'
      });
    }
    if (error.code === 'LIMIT_FILE_COUNT') {
      return res.status(400).json({
        error: 'Слишком много файлов. Максимум: 1 файл'
      });
    }
    if (error.code === 'LIMIT_UNEXPECTED_FILE') {
      return res.status(400).json({
        error: 'Неожиданное поле файла'
      });
    }
  }

  if (error.message) {
    return res.status(400).json({ error: error.message });
  }

  next(error);
});

Лучшие практики обработки ошибок:

  • Информативные сообщения — пользователь должен понять, что пошло не так
  • Логирование — записывайте ошибки в лог для отладки
  • Безопасность — не раскрывайте внутреннюю информацию сервера
  • Консистентность — используйте единый формат ответов с ошибками

Правильная обработка ошибок улучшает пользовательский опыт и упрощает отладку приложения.

8. Загрузка изображений

Загрузка изображений — один из самых распространённых случаев использования Multer. Изображения требуют особого подхода к обработке, включая специфичную валидацию и организацию хранения.

Особенности работы с изображениями:

  • Поддерживаемые форматы — обычно это JPEG, PNG, GIF, WebP
  • Размер файлов — изображения могут быть довольно большими
  • Организация хранения — часто изображения хранят в отдельной папке
  • URL для доступа — нужно предоставить URL для отображения изображений

Специальная настройка для изображений:

const imageStorage = multer.diskStorage({
  destination: function (req, file, cb) {
    cb(null, './uploads/images');
  },
  filename: function (req, file, cb) {
    const uniqueSuffix = Date.now() + '-' + Math.round(Math.random() * 1E9);
    cb(null, 'img-' + uniqueSuffix + path.extname(file.originalname));
  }
});

const imageFilter = (req, file, cb) => {
  const allowedTypes = ['image/jpeg', 'image/png', 'image/gif', 'image/webp'];

  if (allowedTypes.includes(file.mimetype)) {
    cb(null, true);
  } else {
    cb(new Error('Поддерживаются только изображения (JPEG, PNG, GIF, WebP)'), false);
  }
};

const uploadImage = multer({
  storage: imageStorage,
  fileFilter: imageFilter,
  limits: {
    fileSize: 10 * 1024 * 1024 // 10MB для изображений
  }
});

Маршрут для загрузки изображений:

app.post('/upload-image', uploadImage.single('image'), (req, res) => {
  try {
    if (!req.file) {
      return res.status(400).json({ error: 'Изображение не было загружено' });
    }

    res.json({
      message: 'Изображение успешно загружено',
      image: {
        originalname: req.file.originalname,
        filename: req.file.filename,
        mimetype: req.file.mimetype,
        size: req.file.size,
        url: `/uploads/images/${req.file.filename}`
      }
    });
  } catch (error) {
    res.status(500).json({ error: 'Ошибка при загрузке изображения' });
  }
});

Важные моменты для изображений:

  • Префикс в имени файла — используем img- для легкой идентификации
  • Больший лимит размера — 10MB для изображений вместо 5MB
  • URL для доступа — возвращаем URL, по которому можно получить изображение
  • Статические файлы — настраиваем Express для отдачи файлов из папки uploads

Такой подход позволяет создавать галереи изображений, аватары пользователей и другие функции, связанные с изображениями.

9. Безопасность при загрузке файлов

Безопасность при загрузке файлов — критически важный аспект, который нельзя игнорировать. Неправильная обработка файлов может привести к серьёзным уязвимостям.

Основные угрозы безопасности:

  1. Загрузка вредоносных файлов — исполняемые файлы, скрипты
  2. Переполнение диска — загрузка слишком больших файлов
  3. Path traversal — попытки сохранить файлы в неожиданных местах
  4. DoS-атаки — множественные загрузки для перегрузки сервера

Многоуровневая защита:

const secureUpload = multer({
  storage: storage,
  fileFilter: (req, file, cb) => {
    // Проверяем расширение файла
    const allowedExtensions = ['.jpg', '.jpeg', '.png', '.gif', '.pdf', '.txt'];
    const fileExtension = path.extname(file.originalname).toLowerCase();

    if (!allowedExtensions.includes(fileExtension)) {
      return cb(new Error('Недопустимое расширение файла'), false);
    }

    // Проверяем MIME-тип
    const allowedMimeTypes = [
      'image/jpeg', 'image/png', 'image/gif', 
      'application/pdf', 'text/plain'
    ];

    if (!allowedMimeTypes.includes(file.mimetype)) {
      return cb(new Error('Недопустимый тип файла'), false);
    }

    cb(null, true);
  },
  limits: {
    fileSize: 5 * 1024 * 1024, // 5MB
    files: 1,
    fieldNameSize: 50,
    fieldSize: 1024
  }
});

Дополнительные меры безопасности:

  • Очистка имён файлов — удаление опасных символов
  • Ограничение размера полей — предотвращение атак на память
  • Логирование загрузок — отслеживание подозрительной активности
  • Антивирусная проверка — сканирование загруженных файлов

Функция очистки имени файла:

const sanitizeFilename = (filename) => {
  return filename
    .replace(/[^a-zA-Z0-9.-]/g, '_')
    .replace(/_{2,}/g, '_')
    .toLowerCase();
};

Рекомендации по безопасности:

  • Никогда не доверяйте имени файла от пользователя
  • Используйте белые списки вместо чёрных
  • Ограничивайте размеры файлов и количество загрузок
  • Мониторьте активность и логируйте подозрительные действия
  • Регулярно обновляйте зависимости и проверяйте уязвимости

Правильная реализация безопасности защищает не только ваше приложение, но и всю инфраструктуру.

10. Полный пример приложения

Теперь объединим все изученные концепции в одно полноценное приложение. Это приложение демонстрирует лучшие практики работы с Multer и включает все необходимые компоненты для безопасной загрузки файлов.

Структура приложения:

Приложение включает:

  • Автоматическое создание папок для загрузок
  • Умную маршрутизацию файлов по типам
  • Валидацию и безопасность
  • Обработку ошибок
  • API для загрузки одного и нескольких файлов

Основная конфигурация:

const storage = multer.diskStorage({
  destination: function (req, file, cb) {
    if (file.mimetype.startsWith('image/')) {
      cb(null, './uploads/images');
    } else {
      cb(null, './uploads/documents');
    }
  },
  filename: function (req, file, cb) {
    const uniqueSuffix = Date.now() + '-' + Math.round(Math.random() * 1E9);
    const sanitizedName = file.originalname.replace(/[^a-zA-Z0-9.-]/g, '_');
    cb(null, uniqueSuffix + '-' + sanitizedName);
  }
});

const fileFilter = (req, file, cb) => {
  const allowedTypes = [
    'image/jpeg', 'image/png', 'image/gif', 'image/webp',
    'application/pdf', 'text/plain', 'application/msword',
    'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
  ];

  if (allowedTypes.includes(file.mimetype)) {
    cb(null, true);
  } else {
    cb(new Error('Неподдерживаемый тип файла'), false);
  }
};

const upload = multer({
  storage: storage,
  fileFilter: fileFilter,
  limits: {
    fileSize: 10 * 1024 * 1024, // 10MB
    files: 5 // Максимум 5 файлов
  }
});

API маршруты:

app.post('/upload', upload.single('file'), (req, res) => {
  try {
    if (!req.file) {
      return res.status(400).json({ error: 'Файл не загружен' });
    }

    res.json({
      success: true,
      file: {
        originalname: req.file.originalname,
        filename: req.file.filename,
        mimetype: req.file.mimetype,
        size: req.file.size,
        url: `/uploads/${req.file.mimetype.startsWith('image/') ? 'images' : 'documents'}/${req.file.filename}`
      }
    });
  } catch (error) {
    res.status(500).json({ error: 'Ошибка сервера' });
  }
});

Ключевые особенности приложения:

  • Автоматическая организация — изображения и документы сохраняются в разные папки
  • Безопасные имена файлов — удаление опасных символов из имён
  • Умные URL — автоматическое определение правильного пути к файлу
  • Комплексная валидация — проверка типов, размеров и количества файлов
  • Обработка ошибок — информативные сообщения для пользователей

Это приложение готово к использованию в продакшене и может служить основой для более сложных систем загрузки файлов.

Заключение

Multer — это мощный и гибкий middleware для Express.js, который значительно упрощает работу с загрузкой файлов. В этой статье мы рассмотрели все основные аспекты использования Multer, от базовой настройки до продвинутых техник безопасности.

Ключевые выводы:

  1. Простота использования — Multer предоставляет интуитивно понятный API для обработки файлов
  2. Гибкость настройки — можно настроить хранилище, валидацию и ограничения под конкретные нужды
  3. Безопасность — встроенные механизмы защиты, но требуется дополнительная настройка
  4. Производительность — эффективная обработка файлов с минимальными накладными расходами

Основные принципы работы с Multer:

  • Всегда валидируйте файлы — проверяйте тип, размер и расширение
  • Используйте белые списки — разрешайте только нужные типы файлов
  • Обрабатывайте ошибки — предоставляйте понятные сообщения пользователям
  • Организуйте файлы — структурируйте хранение по типам и назначению
  • Устанавливайте лимиты — защищайте сервер от перегрузки

Когда использовать Multer:

  • Загрузка изображений для галерей и профилей
  • Загрузка документов в системах управления контентом
  • Создание файловых хранилищ
  • Обработка форм с файлами
  • Создание API для мобильных приложений

Multer остаётся одним из самых популярных решений для загрузки файлов в экосистеме Node.js, и его изучение — важный шаг в освоении серверной разработки на Express.js.

Читайте также