حين لا تفعل قاعدة Nginx “شيئاً” فالسبب المعتاد أن كتلة location أخرى تولّت الطلب. لا يقرأ Nginx الـ locations من الأعلى إلى الأسفل كما يتوقع كثيرون، بل يتبع ترتيباً محدداً يمزج المطابقة الدقيقة وأطول بادئة والتعابير النمطية. وحين تعرفون الترتيب تزول معظم المفاجآت. يشرحه هذا الدليل ببساطة ويبين كيف تثبتون أي كتلة خدمت عنواناً ويسرد الأخطاء التي تجعل الملفات الثابتة وPHP والوكلاء تتصرف بغير المتوقع.
١. ترتيب المطابقة في صورة واحدة
يتبع Nginx لكل طلب هذه الخطوات. أولاً يبحث عن مطابقة دقيقة (location = /path) فإن وجدها توقف. وإلا يجد أطول location بادئة مطابقة. فإن كانت لتلك البادئة العلامة ^~ توقف عندها. وإلا يختبر locations التعابير النمطية (~ حساسة لحالة الأحرف و~* غير حساسة) بترتيب ظهورها في الملف ويفوز أول تعبير يطابق. وإن لم يطابق أي تعبير استُخدمت أطول بادئة. إليكم مثالاً بالأنواع الأربعة:
server {
listen 80;
server_name example.com;
location = /health { return 200 "ok\n"; } # 1. exact
location ^~ /assets/ { root /var/www/static; } # 2. prefix, stops regex search
location ~* \.(jpg|png|css|js)$ { expires 7d; } # 3. regex (first match wins)
location / { try_files $uri /index.php?$args; } # 4. fallback prefix
}
الطلب إلى /assets/app.css يذهب إلى كتلة ^~ لا كتلة التعبير النمطي رغم انتهائه بـ .css.
٢. لماذا تسرق كتلة regex الطلبات
تُفحص كتل regex بعد مطابقة البادئة البسيطة، فقد يأخذ تعبير واسع طلباً أردتم خدمته من بادئة محددة:
location /uploads/ { root /var/www/site; }
location ~* \.(jpg|png)$ { expires 30d; } # also matches /uploads/a.jpg and wins
الملف تحت /uploads/ ينتهي بـ .jpg فتفوز كتلة regex ولا يُستخدم root الخاص بكتلة البادئة أبداً. وإن أردتم أن تفوز البادئة فأضيفوا إليها ^~. هذه القاعدة الواحدة تفسر بلاغات كثيرة من نوع “ملفاتي الثابتة تعيد 404”.
٣. أثبتوا أي كتلة خدمت الطلب
لا تخمّنوا. اختبروا الإعداد واسردوا الكتل وأضيفوا ترويسة علامة مؤقتة إلى الكتلة التي تفحصونها:
sudo nginx -t
sudo nginx -T 2>/dev/null | grep -nE 'server_name|location '
# Temporary marker header per block (remove after testing)
location /api/ { add_header X-Matched "api" always; proxy_pass http://127.0.0.1:9000; }
ثم اطلبوا العناوين وابحثوا عن الترويسة:
curl -sI http://example.com/health | head -n 3
curl -sI http://example.com/assets/app.css | grep -i x-matched
curl -sI http://example.com/api/v1/items | grep -i x-matched
أزيلوا ترويسة التصحيح بعد ذلك ولا تعيدوا التحميل إلا بعد نجاح nginx -t. وعلى خادم الإنتاج نفّذوا التغيير على نسخة من الملف أو في وقت هادئ.
٤. أسباب شائعة للمفاجآت
تختلف الـ locations المتداخلة عن مستوى الأعلى: كتلة regex داخل كتلة بادئة لا تُؤخذ بالحسبان إلا للطلبات التي طابقت تلك البادئة. وغياب الشرطة المائلة الأخيرة أو زيادتها يغيّر المطابقة ومع proxy_pass المسار المُرسَل. والرجوع الاحتياطي لـ try_files إلى /index.php يطلق بحثاً داخلياً جديداً فقد تأخذ كتلة regex الخاصة بـ PHP الطلب. وتذكروا أن لـ if داخل location غرائب فاستخدموه باعتدال. ولمشاكل الأذونات بعد إيجاد الكتلة الصحيحة راجعوا دليل 403 للأسباب الخاصة بالاستضافة.
٥. أبقوا الإعداد مقروءاً
ضعوا الـ locations الدقيقة والخاصة أولاً للبشر مع أن الترتيب لا يهم إلا للـ regex. واكتبوا تعليقات بجانب القواعد المعتمدة على الترتيب. وأبقوا قواعد الملفات الثابتة ضيقة وتجنبوا تعبيراً ضخماً واحداً لكل شيء. وبالنسبة لـ HSTS والترويسات الموضوعة لكل location تذكروا أن add_header في كتلة ابنة قد يستبدل الترويسات الموروثة؛ راجعوا دليل HSTS.
٦. مثال توضيحي وليس قياساً حقيقياً
افترضوا موقعاً يجب أن تُخدم فيه الملفات تحت /uploads/ من مجلد خاص لكنها تعيد 404 باستمرار (حالة مختلقة). في الإعداد كتلة بادئة لـ /uploads/ وكتلة regex للصور مع التخزين المؤقت. تُظهر ترويسة العلامة أن كتلة regex هي التي خدمت الطلب فتجاهلت root كتلة البادئة. تغيير البادئة إلى ^~ /uploads/ يحلها وترويسة العلامة تثبت السلوك الجديد قبل إزالتها.
٧. أخطاء شائعة
- افتراض أن الـ locations تُقرأ من الأعلى إلى الأسفل.
- نسيان أن regex قد تتجاوز البادئة.
- ترك ترويسات التصحيح في الإنتاج.
- إعادة التحميل قبل تشغيل nginx -t.
- تداخل كتل regex دون فهم النطاق.
- تغيير الشرطة المائلة الأخيرة دون اختبار مسارات الوكيل.
٨. أسئلة شائعة
هل يهم ترتيب locations البادئة؟ لا. يختار Nginx أطول بادئة مطابقة أياً كان الترتيب.
هل يهم ترتيب locations الـ regex؟ نعم. أول تعبير يطابق يفوز.
ماذا تفعل =؟ تعطي مطابقة دقيقة وتُفحص أولاً وهي سريعة جداً فتناسب فحوص الصحة.
هل أختبر دون إعادة تحميل؟ استخدموا nginx -t للصياغة ثم أعيدوا التحميل وافحصوا بـ curl. ونسخة من الإعداد على خادم تجريبي أأمن.
٩. قائمة تحقق سريعة
- شغّلوا nginx -t قبل أي تغيير.
- اسردوا الكتل بـ nginx -T.
- أضيفوا ترويسة علامة مؤقتة.
- اطلبوا العنوان بـ curl.
- استخدموا ^~ حين يجب أن تتغلب البادئة على regex.
- أزيلوا ترويسات التصحيح.
- أعيدوا التحميل واختبروا من جديد.
إذا احتجتم إلى مساعدة في مراجعة الأداء أو صيانة الخادم، فراجعوا خدمات إدارة الخوادم.
تجدون المزيد من أدلة الخوادم وووردبريس في أرشيف المقالات.
المراجع الرسمية
nginx: location directive · nginx: How nginx processes a request · nginx: Beginner’s Guide · nginx: ngx_http_headers_module
