استفاده از multer در Node.js — راهنمای جامع برای آپلود فایل

در توسعه وب با Node.js، آپلود فایل‌ها یکی از نیازهای متداول است. multer یک middleware محبوب برای Express است که پردازش فرم‌های با نوع multipart/form-data را ساده می‌کند. در این مقاله به مفاهیم، نمونه‌کدها، تنظیمات پیشرفته، نکات امنیتی و بهترین رویه‌ها می‌پردازیم.

چرا multer؟

• سادگی در راه‌اندازی برای Express.
• پشتیبانی از ذخیره روی دیسک و حافظه.
• امکان فیلتر کردن فایل‌ها، محدودیت اندازه و نام‌گذاری سفارشی.
• قابل ترکیب با سرویس‌های ذخیره‌سازی ابری (مانند S3) از طریق پلاگین‌ها.

نصب و شروع سریع

npm install express multer

کد بالا بسته‌های لازم را نصب می‌کند. در ادامه یک مثال ساده برای آپلود یک فایل:

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

const app = express();
const upload = multer({ dest: 'uploads/' }); // پیش‌فرض روی دیسک با نام تصادفی

app.post('/upload', upload.single('file'), (req, res) => {
  if (!req.file) return res.status(400).send('No file uploaded.');
  res.send(`Uploaded: ${req.file.originalname}`);
});

app.listen(3000);

در این مثال، multer با گزینه dest فایل‌ها را در پوشه uploads/ ذخیره می‌کند. upload.single('file') منتظر فیلد فرم با نام file است. پس از آپلود، اطلاعات فایل در req.file قرار می‌گیرد.

استفاده از diskStorage برای کنترل نام فایل و مسیر

const storage = multer.diskStorage({
  destination: (req, file, cb) => cb(null, 'uploads/'),
  filename: (req, file, cb) => {
    const ext = path.extname(file.originalname);
    const name = path.basename(file.originalname, ext).replace(/s+/g, '-');
    cb(null, `${Date.now()}-${name}${ext}`);
  }
});

const uploadWithStorage = multer({ storage });

در این کد از diskStorage استفاده شده تا مسیر و نام فایل به‌صورت دلخواه تنظیم شود. افزودن timestamp و پاک‌سازی فاصله‌ها کمک می‌کند نام‌های یکتا و امن تولید شوند.

فیلتر کردن نوع فایل و محدودیت اندازه

const uploadWithFilter = multer({
  storage,
  limits: { fileSize: 5 * 1024 * 1024 }, // حدّ 5 مگابایت
  fileFilter: (req, file, cb) => {
    if (!file.mimetype.startsWith('image/')) {
      return cb(new Error('Only images are allowed'), false);
    }
    cb(null, true);
  }
});

با limits.fileSize اندازه فایل محدود می‌شود و fileFilter برای بررسی نوع MIME به‌کار می‌رود. در صورت عدم تطابق، باید خطا را مدیریت کنید.

آپلود چند فایل و فیلدهای مختلف

// چند فایل با یک فیلد
app.post('/multiple', upload.array('photos', 10), (req, res) => {
  res.send(`Uploaded ${req.files.length} files`);
});

// چند فیلد متفاوت
app.post('/fields', upload.fields([
  { name: 'avatar', maxCount: 1 },
  { name: 'gallery', maxCount: 8 }
]), (req, res) => {
  res.send('Files uploaded');
});

upload.array یک آرایه از فایل‌ها را برمی‌گرداند (req.files)، در حالی که upload.fields برای فیلدهای متعدد کاربرد دارد و نتیجه را به‌صورت آبجکت ارائه می‌دهد.

مقایسه diskStorage و memoryStorage

نمونه ارسال به S3 (تصویری از روش بهینه)

برای ارسال مستقیم به S3 بهتر است از پلاگین multer-s3 استفاده کنید تا فایل‌ها مستقیم به فضای ابری جریان یابند و از حافظه سرور عبور نکنند. ساختار کلی:

const multerS3 = require('multer-s3');
const AWS = require('aws-sdk');
const s3 = new AWS.S3();

const uploadS3 = multer({
  storage: multerS3({
    s3,
    bucket: 'my-bucket',
    key: (req, file, cb) => cb(null, `uploads/${Date.now()}-${file.originalname}`)
  })
});

این راهکار مناسب پروژه‌هایی است که نیاز به مقیاس‌پذیری و ذخیره‌سازی ابری دارند. مطمئن شوید IAM و تنظیمات S3 به‌درستی پیکربندی شده است.

خطاها و نحوه مدیریت آن‌ها

• خطاهای multer (مانند اندازه بیشتر از حد) با نوع MulterError بازمی‌گردند؛ آن‌ها را در middleware خطا هندل کنید.
• در صورت تکرار نام فایل یا مسیرهای موقت، پاک‌سازی دستی فایل‌های ناخواسته را انجام دهید.

نکات امنیتی و بهترین رویه‌ها

• همیشه نوع فایل و اندازه را بررسی کنید.
• نام فایل‌ها را نپذیرید؛ آن‌ها را sanitize و بازنامگذاری کنید تا از path traversal جلوگیری شود.
• برای فایل‌های حساس، اسکن آنتی‌ویروس پس از آپلود را مد نظر قرار دهید.
• در صورت ذخیره در پوشه عمومی، دسترسی‌ها و سرویس‌دهنده فایل را محدود کنید.
• محدودیت تعداد فایل‌ها (maxCount) را اعمال کنید تا DoS از طریق آپلودهای متعدد کاهش یابد.

رفع مشکلات رایج

• اگر req.file یا req.files خالی است: مطمئن شوید فرم از نوع enctype="multipart/form-data" ارسال می‌شود.
• خطاهای مجوز فایل: بررسی کنید پوشه uploads/ قابلیت نوشتن دارد.
• فایل‌ها حذف نمی‌شوند: برای پاک‌سازی برنامه‌ریزی‌شده از cron یا وظایف پس‌زمینه استفاده کنید.

خلاصه و جمع‌بندی

multer یک ابزار قوی و منعطف برای مدیریت آپلود در Node.js است. با تنظیمات مناسب ذخیره، فیلترها و محدودیت‌ها، می‌توانید یک سیستم آپلود امن و مقیاس‌پذیر بسازید. برای بارگذاری به سرویس‌های ابری از راهکارهای مستقیم مانند multer-s3 استفاده کنید تا فشار روی سرور کاهش یابد. در نهایت، کیفیت کار به رعایت نکات امنیتی، مدیریت خطا و پاک‌سازی منابع وابسته است.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال