کانفیگ nginx برای React، Vue و Angular (SPA)
برنامههای تکصفحهای (SPA) مسیرهایی مثل /dashboard دارند که فایل واقعی ندارند. nginx باید همهٔ آنها را به index.html بدهد. اشتباه رایج این است که صفحه با refresh 404 میدهد؛ این کانفیگ آن را حل میکند.
۱بیلد پروژه و کپی خروجی
پروژه را بیلد کنید و خروجی (dist یا build) را روی سرور بگذارید.
npm ci && npm run build
rsync -az --delete dist/ user@server:/var/www/app/۲کانفیگ SPA
try_files ابتدا فایل واقعی را میجوید و در صورت نبود index.html را برمیگرداند تا router سمت کلاینت کار کند.
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 روی یک دامنه باشند.
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 بگیرید.
sudo nginx -t && sudo systemctl reload nginx
curl -I http://app.example.com/dashboard/settings۵زیرمسیر (base path)
اگر برنامه روی /app/ سرو میشود، base را در ابزار بیلد (Vite: base و React Router: basename) هم تنظیم کنید.
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 شده این مشکل حل میشود.