كيفية إصلاح خطأ 413 في طلب الكيان الكبير جدًا في Nginx وNode.js

الخطأ413 طلب الكيان كبير جدًا يعني أن نص الطلب (عادةً تحميل ملف أو حمولة JSON كبيرة) يتجاوز الحد الأقصى للحجم الذي يسمح به خادمك. غالبًا ما يظهر فقط في الإنتاج بسبب إعدادات nginx الافتراضية. وإليك كيفية إصلاحه في كل طبقة.

ما الذي يسبب هذا الخطأ

يمكن للطبقات المتعددة رفض طلب كبير:

• نجينكس (الوكيل العكسي) له حد افتراضي يبلغ 1 ميجابايت
• Express/Node.js المحلل اللغوي له حد خاص به (افتراضي ~ 100 كيلو بايت)
• تحميل الوسيطة (multer) له حدود حجم ملف قابلة للتكوين

يجب أن يجتاز الطلب جميع الطبقات — فإصلاح طبقة واحدة فقط قد لا يحل المشكلة.

الإصلاح 1: Nginx client_max_body_size

# nginx is the most common culprit — default is 1MB

# In your server or location block:
server {
    # Allow up to 50MB request bodies
    client_max_body_size 50M;

    location /api/upload {
        client_max_body_size 100M;   # larger for upload endpoints
        proxy_pass http://localhost:3000;
    }
}

# Or globally in http block (/etc/nginx/nginx.conf):
http {
    client_max_body_size 50M;
}

# Reload nginx after changing
sudo nginx -t && sudo systemctl reload nginx

الإصلاح 2: حد محلل الجسم السريع

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

// 🐛 Default limit is ~100KB — large JSON fails
app.use(express.json());

// ✅ Increase the limit
app.use(express.json({ limit: '50mb' }));
app.use(express.urlencoded({ limit: '50mb', extended: true }));

// For specific routes only:
app.post('/api/large', express.json({ limit: '100mb' }), handler);

الإصلاح 3: حدود تحميل الملفات المتعددة

const multer = require('multer');

// Configure size limits for file uploads
const upload = multer({
  storage: multer.diskStorage({ /* ... */ }),
  limits: {
    fileSize: 50 * 1024 * 1024,   // 50MB per file
    files: 5,                      // max 5 files
  },
});

app.post('/upload', upload.single('file'), (req, res) => {
  res.json({ filename: req.file.filename });
});

// Handle multer's own limit error gracefully
app.use((err, req, res, next) => {
  if (err instanceof multer.MulterError && err.code === 'LIMIT_FILE_SIZE') {
    return res.status(413).json({ error: 'File too large (max 50MB)' });
  }
  next(err);
});

الطبقات الثلاث معًا

لكي ينجح التحميل بحجم 50 ميجابايت، يجب أن تسمح كافة الحدود بذلك:

# 1. nginx (if used as reverse proxy)
client_max_body_size 50M;

# 2. Express body parser (for JSON/form data)
app.use(express.json({ limit: '50mb' }));

# 3. Multer (for multipart file uploads)
limits: { fileSize: 50 * 1024 * 1024 }

# The SMALLEST limit wins — the request fails at the first layer that rejects it

إصلاح للخوادم الأخرى

# Apache — in .htaccess or config
LimitRequestBody 52428800   # 50MB in bytes

# Cloudflare — free plan limits uploads to 100MB
# (upgrade or upload directly to storage for larger files)

# Next.js API routes — configure the body size limit
export const config = {
  api: {
    bodyParser: { sizeLimit: '50mb' },
  },
};

نهج أفضل: التحميل مباشرة إلى تخزين الكائنات

بالنسبة للملفات الكبيرة، لا تقم بتوجيهها عبر خادم التطبيق الخاص بك على الإطلاق — استخدم عناوين URL الموقعة مسبقًا للتحميل مباشرةً إلى S3/التخزين السحابي:

// Backend generates a presigned upload URL
app.post('/api/presign', async (req, res) => {
  const url = await s3.getSignedUrl('putObject', {
    Bucket: 'my-bucket',
    Key: `uploads/${req.body.filename}`,
    Expires: 300,
  });
  res.json({ uploadUrl: url });
});

// Frontend uploads directly to S3 — bypasses your server's limits entirely
const { uploadUrl } = await fetch('/api/presign', { /* ... */ }).then(r => r.json());
await fetch(uploadUrl, { method: 'PUT', body: file });
// No 413 — the file never passes through your app server

الأسئلة المتداولة

س: لماذا يعمل محليا ويفشل في الإنتاج؟
ج: عادةً ما يكون للإنتاج nginx (أو وكيل عكسي آخر) أمام تطبيقك بحد افتراضي يبلغ 1 ميجابايت. محليًا، يمكنك الضغط على تطبيقك مباشرةً بدون هذا الوكيل. زيادةclient_max_body_size في نجينكس.

س: لقد قمت بزيادة الحد الأقصى لخدمة Express ولكنني مازلت أحصل على 413. لماذا؟
ج: يرفض nginx الطلب قبل أن يصل إلى Express. الوكيل العكسيclient_max_body_size يجب أيضًا زيادتها. أصلح جميع الطبقات — أصغر حد يفوز.

س: ما هو الحد المعقول لحجم الجسم؟
ج: قم بضبطه عند أدنى مستوى تسمح به حالة الاستخدام الخاصة بك — فالحدود الكبيرة تزيد من خطر إساءة الاستخدام/DoS. بالنسبة لواجهات برمجة تطبيقات JSON، فإن القليل من الميغابايت يعتبر كافيًا. بالنسبة لعمليات تحميل الملفات، قم بحجم أكبر ملف شرعي لديك، أو الأفضل من ذلك، قم بالتحميل مباشرة إلى وحدة تخزين الكائنات.

س: هل يجب أن تمر الملفات الكبيرة عبر خادم التطبيق الخاص بي على الإطلاق؟
ج: من الناحية المثالية لا – استخدم عناوين URL المحددة مسبقًا للتحميل مباشرة إلى S3/التخزين السحابي. يؤدي هذا إلى تجنب حدود حجم الجسم تمامًا، ويقلل من حمل الخادم، ويتوسع بشكل أفضل. قم بتوجيه البيانات الوصفية فقط من خلال تطبيقك.

س: كيف يمكنني إرجاع خطأ مألوف بدلاً من الخطأ 413 الأولي؟
ج: اكتشف خطأ الحد في برنامجك الوسيط (حجم LIMIT_FILE_SIZE المتعدد، أو خطأ المحلل اللغوي) وقم بإرجاع رسالة JSON واضحة. تحقق أيضًا من حجم الملف على الواجهة الأمامية قبل التحميل لتقديم تعليقات فورية.

الخلاصة

“413 كيان الطلب كبير جدًا” يعني أن نص الطلب يتجاوز حد الخادم – وغالبًا ما يحتوي على طبقات متعددة. الإصلاح:زيادةclient_max_body_size في nginx، ارفع المحلل اللغوي لـ Expresslimit، وقم بتكوينfileSize – يجب أن يسمح الثلاثة جميعًا بالحجم نظرًا لأن الحد الأصغر هو الذي يفوز. يظهر عادةً في الإنتاج بسبب الإعداد الافتراضي لـ nginx وهو 1 ميجابايت. بالنسبة للملفات الكبيرة، فإن الحل الأفضل هو التحميل مباشرة إلى وحدة تخزين الكائنات باستخدام عناوين URL الموقعة مسبقًا، وتجاوز حدود خادم التطبيق الخاص بك بالكامل والتوسع بشكل أفضل.