کانفیگ nginx برای React، Vue و Angular (SPA)

برنامه‌های تک‌صفحه‌ای (SPA) مسیرهایی مثل /dashboard دارند که فایل واقعی ندارند. nginx باید همهٔ آن‌ها را به index.html بدهد. اشتباه رایج این است که صفحه با refresh 404 می‌دهد؛ این کانفیگ آن را حل می‌کند.

وب‌سرور و SSLمقدماتی6 دقیقه

۱بیلد پروژه و کپی خروجی

پروژه را بیلد کنید و خروجی (dist یا build) را روی سرور بگذارید.

bash
npm ci && npm run build
rsync -az --delete dist/ user@server:/var/www/app/

۲کانفیگ SPA

try_files ابتدا فایل واقعی را می‌جوید و در صورت نبود index.html را برمی‌گرداند تا router سمت کلاینت کار کند.

nginx
server {
    listen 80;
    server_name app.example.com;

    root /var/www/app;
    index index.html;

    # مسیرهای SPA
    location / {
        try_files $uri $uri/ /index.html;
    }

    # فایل‌های hash شده: کش یک‌ساله
    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
    }

    # index.html هرگز کش نشود تا نسخهٔ جدید فوراً دیده شود
    location = /index.html {
        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    gzip on;
    gzip_types text/css application/javascript application/json image/svg+xml;
}

۳پروکسی کردن API به بک‌اند

درخواست‌های /api را به سرور بک‌اند بدهید تا از مشکل CORS پیشگیری شود و کلاینت و API روی یک دامنه باشند.

nginx
    location /api/ {
        proxy_pass http://127.0.0.1:4000/;
        proxy_http_version 1.1;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

این بلوک را قبل از location / بگذارید؛ یا ترتیب فرقی نمی‌کند ولی مطمئن شوید /api/ فایل استاتیک نیست.

۴اعمال و تست

مسیر عمیق را مستقیم در مرورگر باز کنید و refresh بزنید؛ نباید 404 بگیرید.

bash
sudo nginx -t && sudo systemctl reload nginx
curl -I http://app.example.com/dashboard/settings

۵زیرمسیر (base path)

اگر برنامه روی /app/ سرو می‌شود، base را در ابزار بیلد (Vite: base و React Router: basename) هم تنظیم کنید.

nginx
    location /app/ {
        alias /var/www/app/;
        try_files $uri $uri/ /app/index.html;
    }

پرسش‌های پرتکرار دربارهٔ کانفیگ nginx برای React، Vue و Angular (SPA)

چرا بعد از deploy نسخهٔ جدید دیده نمی‌شود؟

احتمالاً index.html کش شده است. با Cache-Control: no-cache برای index.html و کش بلند برای فایل‌های hash شده این مشکل حل می‌شود.