همه مقالات تخصصی

ترتیب تطبیق location در Nginx: کدام بلاک واقعاً درخواست را سرو می‌کند

تطبیق exact، prefix، ^~ و regex در location های Nginx را بفهمید و با هدر موقت ثابت کنید کدام بلاک درخواست را سرو می‌کند.

ترتیب تطبیق location در Nginx: کدام بلاک واقعاً درخواست را سرو می‌کند

وقتی یک قاعدهٔ Nginx «هیچ کاری نمی‌کند»، دلیل معمول این است که location دیگری درخواست را گرفته. Nginx locationها را آن‌طور که خیلی‌ها انتظار دارند از بالا به پایین نمی‌خواند. ترتیب مشخصی دارد که تطبیق دقیق، بلندترین prefix و عبارت منظم را قاطی می‌کند. وقتی ترتیب را بدانید بیشتر غافلگیری‌ها از بین می‌روند. این راهنما آن را ساده توضیح می‌دهد، نشان می‌دهد چطور ثابت کنید کدام بلاک یک URL را سرو کرده و اشتباه‌هایی را که باعث رفتار غیرمنتظرهٔ فایل‌های ایستا، PHP و پروکسی می‌شوند فهرست می‌کند.

۱. ترتیب تطبیق در یک تصویر

Nginx برای هر درخواست این گام‌ها را می‌رود. اول دنبال تطبیق دقیق می‌گردد (location = /path)؛ اگر یافت همان‌جا می‌ایستد. وگرنه بلندترین location پیشوندی منطبق را پیدا می‌کند. اگر آن prefix مُعدِّل ^~ داشته باشد همان‌جا می‌ایستد. اگر نه، locationهای regex (~ حساس به حروف و ~* بدون حساسیت) را به ترتیب ظاهرشدن در فایل تست می‌کند و اولین regex منطبق برنده است. اگر هیچ regex منطبق نشد، بلندترین prefix استفاده می‌شود. مثالی با چهار نوع:

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 به بلاک ^~ می‌رود نه بلاک regex، با اینکه به .css ختم می‌شود.

۲. چرا بلاک regex درخواست را می‌دزدد

بلاک‌های regex بعد از تطبیق prefix ساده بررسی می‌شوند، پس regex گسترده می‌تواند درخواستی را بگیرد که می‌خواستید از prefix مشخصی سرو شود:

location /uploads/ { root /var/www/site; }
location ~* \.(jpg|png)$ { expires 30d; }   # also matches /uploads/a.jpg and wins

فایل زیر /uploads/ به .jpg ختم می‌شود، پس بلاک regex برنده است و root بلاک prefix هرگز استفاده نمی‌شود. اگر می‌خواهید prefix ببرد، ^~ به آن اضافه کنید. همین یک قانون بسیاری از گزارش‌های «فایل‌های ایستای من ۴۰۴ می‌دهند» را توضیح می‌دهد.

۳. ثابت کنید کدام بلاک سرو کرده

حدس نزنید. پیکربندی را تست کنید، بلاک‌ها را فهرست کنید و به بلاکی که بررسی می‌کنید هدر نشانگر موقت بدهید:

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; }

بعد URLها را درخواست کنید و هدر را بیابید:

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 reload کنید. روی سرور تولید تغییر را در نسخهٔ کپی فایل یا زمان کم‌ترافیک بدهید.

۴. علت‌های رایج غافلگیری

locationهای تودرتو با سطح بالا فرق دارند: بلاک regex داخل بلاک prefix فقط برای درخواست‌هایی در نظر گرفته می‌شود که با آن prefix منطبق شده‌اند. اسلش انتهایی کم یا زیاد تطبیق و با proxy_pass مسیر ارسالی را عوض می‌کند. fallback مربوط به try_files به /index.php جست‌وجوی داخلی تازه‌ای می‌زند و ممکن است بلاک regex مربوط به PHP درخواست را بگیرد. یادتان باشد if داخل location ظرافت‌هایی دارد و باید کم استفاده شود. برای مشکل دسترسی بعد از یافتن بلاک درست راهنمای 403 را برای علت‌های مخصوص هاست ببینید.

۵. پیکربندی را خوانا نگه دارید

برای انسان‌ها locationهای exact و خاص را اول بگذارید، با اینکه ترتیب فقط برای regex مهم است. کنار قاعده‌هایی که به ترتیب وابسته‌اند کامنت بگذارید. قاعده‌های فایل ایستا را باریک نگه دارید و از یک regex غول‌آسا برای همه‌چیز پرهیز کنید. برای HSTS و هدرهایی که در هر location گذاشته می‌شوند یادتان باشد add_header در بلاک فرزند می‌تواند هدرهای ارثی را جایگزین کند؛ راهنمای HSTS را ببینید.

۶. مثال توضیحی، نه اندازه‌گیری واقعی

فرض کنید سایتی فایل‌های زیر /uploads/ را باید از پوشهٔ خاصی سرو کند اما مدام ۴۰۴ می‌دهند (موردی ساختگی). پیکربندی یک بلاک prefix برای /uploads/ و یک بلاک regex برای تصاویر با کش دارد. افزودن هدر نشانگر نشان می‌دهد بلاک regex درخواست را سرو کرده و root بلاک prefix نادیده گرفته شده. تغییر prefix به ^~ /uploads/ حلش می‌کند و هدر نشانگر رفتار جدید را قبل از حذف ثابت می‌کند.

۷. اشتباه‌های رایج

  • فرض اینکه locationها از بالا به پایین خوانده می‌شوند.
  • فراموش‌کردن اینکه regex می‌تواند prefix را بازنویسی کند.
  • جاگذاشتن هدرهای دیباگ در تولید.
  • reload قبل از اجرای nginx -t.
  • تودرتوکردن بلاک‌های regex بدون فهم دامنه.
  • تغییر اسلش انتهایی بدون تست مسیر پروکسی.

۸. پرسش‌های متداول

ترتیب locationهای prefix مهم است؟ نه. Nginx بدون توجه به ترتیب بلندترین prefix منطبق را انتخاب می‌کند.

ترتیب locationهای regex مهم است؟ بله. اولین regex منطبق برنده است.

= چه می‌کند؟ تطبیق دقیق می‌دهد و اول بررسی می‌شود. خیلی هم سریع است و برای health check مناسب است.

بدون reload می‌توانم تست کنم؟ برای syntax از nginx -t استفاده کنید، بعد reload و با curl بررسی کنید. کپی پیکربندی روی سرور آزمایشی امن‌تر است.

۹. چک‌لیست سریع

  1. قبل از هر تغییر nginx -t بزنید.
  2. بلاک‌ها را با nginx -T فهرست کنید.
  3. هدر نشانگر موقت اضافه کنید.
  4. URL را با curl درخواست کنید.
  5. وقتی prefix باید از regex ببرد ^~ بگذارید.
  6. هدرهای دیباگ را حذف کنید.
  7. reload و دوباره تست کنید.

اگر برای بررسی عملکرد یا نگهداری سرور به همکاری نیاز دارید، محدودهٔ خدمات مدیریت سرور را ببینید.

راهنماهای بیشتر سرور و وردپرس در آرشیو مقالات جمع شده‌اند.

منابع رسمی

nginx: location directive · nginx: How nginx processes a request · nginx: Beginner’s Guide · nginx: ngx_http_headers_module