Multer لجافا سكريبت (Node.js): دليل شامل مع أمثلة

1. ما هي Multer ولماذا نحتاجها؟

Multer هي مكتبة وسيطة (middleware) شهيرة لـ Node.js، مصممة لمعالجة بيانات multipart/form-data — وهو التنسيق المستخدم عند رفع الملفات عبر نماذج HTML. على عكس الوحدة القياسية body-parser التي تعمل فقط مع بيانات JSON وبيانات URL المشفرة، تستطيع Multer تحليل الطلبات المركبة، واستخراج الملفات منها، وحفظها على الخادم (في الذاكرة أو على القرص). المكتبة مبنية فوق وحدة busboy وتوفر واجهة برمجة تطبيقات (API) مريحة لتكوين المسارات، وأسماء الملفات، وتصفية الأنواع، وتحديد الحجم.

لماذا نحتاج Multer؟ في أي تطبيق ويب حيث يمكن للمستخدم رفع صورة شخصية، أو مستند، أو صورة، أو فيديو، يجب معالجة multipart/form-data. إطار العمل Express.js (الإطار الأكثر شيوعًا لـ Node.js) لا يحتوي على دعم مدمج لهذا التنسيق، لذلك تصبح Multer أداة أساسية. تتيح للمطور التركيز على منطق الأعمال بدلاً من التحليل منخفض المستوى للبيانات الثنائية.

تدعم Multer رفع ملف واحد أو عدة ملفات في وقت واحد، والعمل مع حقول النموذج، وإنشاء أسماء ملفات مخصصة، والتصفية حسب أنواع MIME والامتدادات، بالإضافة إلى تحديد حجم البيانات المرفوعة. بفضل مرونة التكوين، تناسب المكتبة كلاً من المشاريع البسيطة (مثل رفع الصور الشخصية) والأنظمة المعقدة ذات التخزين السحابي (من خلال وحدات التخزين المخصصة).

2. التثبيت

يتم التثبيت عبر npm (مدير حزم Node). تأكد من تثبيت Node.js (الإصدار 12 أو أحدث).

npm install multer

بعد التثبيت، ستكون المكتبة متاحة للاستيراد في مشروعك.

3. بداية سريعة — مثال عملي بسيط

لنقم بإنشاء خادم بسيط باستخدام Express.js، يستقبل رفع ملف واحد عبر نموذج ويحفظه في مجلد uploads/.

الخطوة 1. هيكل المشروع

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

الخطوة 2. نموذج HTML (index.html)

<!DOCTYPE html>
<html lang="ar">
<head>
    <meta charset="UTF-8">
    <title>رفع ملف</title>
</head>
<body>
    <h1>قم برفع ملفك</h1>
    <form action="/upload" method="POST" enctype="multipart/form-data">
        <input type="file" name="myFile" required>
        <button type="submit">إرسال</button>
    </form>
</body>
</html>

الخطوة 3. الخادم (server.js)

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

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

// إعداد Multer: سيتم حفظ الملفات في مجلد 'uploads/'
const storage = multer.diskStorage({
    destination: (req, file, cb) => {
        cb(null, 'uploads/');
    },
    filename: (req, file, cb) => {
        // إنشاء اسم فريد: التاريخ الحالي + الامتداد الأصلي
        const uniqueSuffix = Date.now() + '-' + Math.round(Math.random() * 1E9);
        cb(null, uniqueSuffix + path.extname(file.originalname));
    }
});

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

// تقديم ملف HTML الثابت
app.get('/', (req, res) => {
    res.sendFile(__dirname + '/index.html');
});

// معالجة رفع الملف
app.post('/upload', upload.single('myFile'), (req, res) => {
    if (!req.file) {
        return res.status(400).send('لم يتم رفع الملف.');
    }
    res.send(`تم رفع الملف "${req.file.originalname}" بنجاح. الحجم: ${req.file.size} بايت.`);
});

app.listen(PORT, () => {
    console.log(`الخادم يعمل على المنفذ ${PORT}`);
});