شرح قواعد مطابقة Nginx Location مع أمثلة واقعية

من المحتمل أنك قمت بتعديل إعدادات Nginx، ثم أعدت التحميل، وتساءلت لماذا لا يبدو أن كتلة location الخاصة بك تُطبَّق. ربما طلب ملف ثابت يصل إلى معالج PHP، أو مسار API يُبتلع بواسطة قاعدة شاملة. السبب غالبًا هو خوارزمية مطابقة location في Nginx—فهي ليست بسيطة كما تبدو.

في هذا الدليل، سنشرح كيفية اختيار Nginx لكتلة location، مع أمثلة واقعية يمكنك اختبارها. بحلول النهاية، ستعرف بالضبط أي كتلة تفوز ولماذا.

كيف تعمل مطابقة Nginx Location

عند وصول طلب، يقارن Nginx الـ URI مع جميع كتل location المعرّفة. تتبع عملية المطابقة ترتيبًا محددًا:

1. المطابقة الدقيقة (=) — أعلى أولوية. إذا وُجدت، يتوقف Nginx ويستخدمها.
2. أطول مطابقة بادئة — يتذكر Nginx أطول location بادئة مطابقة.
3. مطابقة التعبير النمطي (~ أو ~*) — تُفحص بترتيب ظهورها. أول regex يطابق يفوز، متجاوزًا مطابقة البادئة (إلا إذا استُخدم ^~).
4. مطابقة البادئة مع ^~ — إذا كانت أطول بادئة مطابقة تحتوي على ^~، يتخطى Nginx فحص regex ويستخدمها.
5. إذا لم يطابق أي regex، تُستخدم أطول مطابقة بادئة.

هذه هي الخوارزمية الأساسية. لنرها أثناء العمل.

معدّلات Location: مرجع سريع

مثال واقعي 1: الملفات الثابتة مقابل PHP

لنأخذ هذا الإعداد الشائع:

server {
    listen 80;
    server_name example.com;

    location / {
        root /var/www/html;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    }
}

طلب /index.php يطابق regex \.php$، لذا يذهب إلى PHP-FPM. طلب /logo.png لا يطابق regex، لذا يعود إلى البادئة / ويقدّم الملف الثابت. بسيط، صحيح؟

لكن ماذا لو أردت تقديم /uploads/photo.php كملف ثابت (ربما هي صورة فعلاً)؟ يمكنك إضافة مطابقة دقيقة:

location = /uploads/photo.php {
    root /var/www/html;
}

الآن هذه المطابقة الدقيقة تتقدم على regex.

مثال واقعي 2: توجيه API باستخدام البادئة و regex

افترض أن لديك API تحت /api/ وتريد تمرير جميع الطلبات إلى خادم خلفي، باستثناء فحص صحي يُرجع استجابة ثابتة.

location = /api/health {
    return 200 "OK";
}

location /api/ {
    proxy_pass http://backend;
}

location ~ ^/api/v[0-9]+/special {
    proxy_pass http://special-backend;
}

لنتتبع /api/health: المطابقة الدقيقة تفوز، وتُرجع 200. لـ /api/users: لا مطابقة دقيقة، لا regex (لا يطابق special)، لذا تُستخدم أطول بادئة /api/. لـ /api/v1/special: يطابق regex، لذا يتجاوز البادئة ويذهب إلى special-backend.

يوضح هذا كيف يمكن لـ regex تجاوز مطابقة البادئة. إذا أردت أن تفوز البادئة دائمًا، فاستخدم ^~ بدلاً من ذلك.

مثال واقعي 3: قوة ^~

تخيل أن لديك مجلد /static/ يحتوي على ملفات لا يجب أن يعالجها PHP أبدًا، حتى لو انتهت بـ .php. استخدام ^~ يضمن ألا يفحص Nginx مواقع regex.

location ^~ /static/ {
    root /var/www/html;
}

location ~ \.php$ {
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
}

طلب /static/script.php يطابق البادئة ^~ /static/. بسبب ^~، يتخطى Nginx فحص regex ويقدّم الملف مباشرة. بدون ^~، سيطابق regex وسينفذه PHP-FPM—وهو خطر أمني محتمل.

المزالق الشائعة وكيفية تجنبها

• ترتيب regex مهم: يفحص Nginx مواقع regex بالترتيب الذي تظهر به في الإعدادات. ضع الأنماط الأكثر تحديدًا أولاً.
• الشرطة المائلة النهائية المفقودة: location /api و location /api/ مختلفان. الأول يطابق /api و /apix، بينما الثاني يطابق /api/ و /api/users. كن دقيقًا.
• البادئات المتداخلة: الأطول بادئة تفوز، لذا location /api/v1 يتقدم على location /api لـ /api/v1/users.
• نسيان ^~ للأصول الثابتة: استخدمه لمنع regex من اختطاف طلبات الملفات الثابتة.
• حساسية حالة الأحرف: ~ حساس لحالة الأحرف، ~* غير حساس. استخدم ~* لامتدادات الملفات.

تصحيح مطابقة Location

إذا لم تكن متأكدًا من أي location يُستخدم، فعّل تسجيل التصحيح في Nginx. أضف error_log /var/log/nginx/error.log debug; في كتلة server، أعد التحميل، وافحص السجل. سترى أسطرًا مثل test location: "/api/users" و using configuration "/api/".

بدلاً من ذلك، استخدم return 200 "matched: /api/"; مؤقتًا في كل location لترى أيها يستجيب.

الأسئلة الشائعة

ما هو ترتيب أولوية معدّلات Nginx location؟

المطابقة الدقيقة (=) هي الأعلى، ثم أطول بادئة مع ^~، ثم regex (~ أو ~*) بالترتيب، ثم أطول مطابقة بادئة بدون ^~.

هل يمكن لـ location regex تجاوز location بادئة؟

نعم، إلا إذا استخدم location البادئة ^~. تُفحص مواقع regex بعد أطول مطابقة بادئة، وإذا طابق regex، فإنه يتقدم على البادئة العادية.

كيف أطابق location لملف محدد فقط؟

استخدم مطابقة دقيقة مع =، مثل location = /favicon.ico. هذا يضمن مطابقة ذلك الـ URI بالضبط فقط.

أتقن إعدادات Nginx الخاصة بك

فهم مطابقة location هو مفتاح إعداد Nginx موثوق. اختبر إعداداتك باستخدام nginx -t واستخدم سجلات التصحيح عند الشك. إذا كنت تتعامل مع سجلات Nginx وتحتاج إلى تحليل أنماط الزيارات، جرّب Nginx Log Analyzer لتحليل سجلاتك وتصورها بسرعة.