Node.js 파일 업로드와 이미지 처리(multer + sharp)

소개

웹 애플리케이션에서 이미지 업로드는 매우 흔한 기능이다. 용량 관리와 응답 속도를 위해 업로드된 이미지를 서버에서 리사이즈하거나 최적화하는 경우가 많다. 이 글에서는 Express 기반의 Node.js 환경에서 "Node 파일 업로드 multer 사용법", "multer sharp 이미지 리사이즈", "Node.js 이미지 업로드 처리" 키워드를 중심으로 multer와 sharp를 이용한 실제 구현 예를 설명한다.

필요한 패키지와 기본 개념

이미지 업로드와 처리를 위해 다음 패키지가 주로 사용된다.

• express: 라우팅과 서버 구성
• multer: multipart/form-data 파싱 및 파일 업로드
• sharp: 이미지 리사이즈와 포맷 변환

간단한 설치 예시:

npm install express multer sharp

multer 설정

multer는 업로드 파일을 디스크 또는 메모리에 저장한다. 보통 파일 필터와 크기 제한을 함께 설정해 보안과 안정성을 확보한다.

디스크 저장 예제

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

const storage = multer.diskStorage({
  destination: function (req, file, cb) {
    cb(null, path.join(__dirname, 'uploads'));
  },
  filename: function (req, file, cb) {
    const ext = path.extname(file.originalname);
    const name = Date.now() + '-' + Math.round(Math.random() * 1e9) + ext;
    cb(null, name);
  }
});

const fileFilter = (req, file, cb) => {
  if (file.mimetype.startsWith('image/')) cb(null, true);
  else cb(new Error('이미지 파일만 허용')); 
};

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

메모리 저장 예제

이미지를 즉시 처리하고 디스크에 저장하기 전에 변환을 적용하고 싶을 때 메모리 저장을 사용하면 편리하다.

const uploadMemory = multer({ storage: multer.memoryStorage(), fileFilter, limits: { fileSize: 5 * 1024 * 1024 } });

sharp를 이용한 이미지 리사이즈

sharp는 빠른 이미지 처리 라이브러리다. 리사이즈, 포맷 변환, 품질 조절 등을 지원한다. multer의 메모리 저장을 사용하면 버퍼를 직접 전달해 처리할 수 있다.

const sharp = require('sharp');
const fs = require('fs');
const path = require('path');

async function resizeAndSave(buffer, filename, width = 800) {
  const outputPath = path.join(__dirname, 'uploads', filename);
  await sharp(buffer)
    .resize({ width, withoutEnlargement: true })
    .toFormat('jpeg')
    .jpeg({ quality: 80 })
    .toFile(outputPath);
  return outputPath;
}

라우트 구성 예제

다음 예시는 단일 파일 업로드와 리사이즈를 수행한 뒤 저장 경로를 응답으로 반환하는 라우트다.

const express = require('express');
const app = express();

app.post('/upload', uploadMemory.single('image'), async (req, res) => {
  try {
    if (!req.file) return res.status(400).json({ error: '파일 없음' });
    const filename = Date.now() + '.jpg';
    const savedPath = await resizeAndSave(req.file.buffer, filename, 1024);
    res.json({ path: savedPath });
  } catch (err) {
    console.error(err);
    res.status(500).json({ error: '이미지 처리 실패' });
  }
});

app.listen(3000, () => console.log('Server started'));

실무 고려사항

파일 업로드와 이미지 처리는 단순 구현 외에 여러 요소를 고려해야 한다.

• 보안: MIME 타입 검사, 확장자 검증, 파일 크기 제한 적용
• 성능: 동시 업로드가 많은 경우 비동기 처리와 워커 사용을 검토
• 저장소: 로컬 디스크 대신 클라우드(S3 등)를 사용하면 확장성과 백업 용이
• 에러 처리: 잘못된 파일 또는 처리 실패 시 사용자 친화적 응답 설계

에러와 예외 처리

multer와 sharp에서 발생하는 에러는 구분해서 처리하는 편이 안전하다. multer의 미들웨어 에러는 Express 에러 핸들러에서 잡을 수 있다.

app.use((err, req, res, next) => {
  if (err instanceof multer.MulterError) {
    return res.status(400).json({ error: '업로드 제한 초과' });
  }
  res.status(500).json({ error: err.message || '서버 에러' });
});

요약 및 권장 설정

multer와 sharp 조합은 Node.js에서 이미지 업로드와 최적화를 효율적으로 구현할 수 있게 한다. 핵심 포인트는 다음과 같다.

• 파일 필터와 크기 제한으로 기본 보안 확보
• 메모리 저장 후 sharp로 처리하면 유연한 변환 가능
• 생산 환경에서는 클라우드 저장과 큐를 통한 비동기 처리를 고려

위 내용을 바탕으로 프로젝트 요구에 맞는 업로드 정책과 이미지 처리 파이프라인을 설계하면 안정적이고 확장 가능한 이미지 업로드 기능을 구현할 수 있다.