نشر تطبيق Nuxt على VPS

لماذا تستضيف Nuxt ذاتيًا على VPS؟

فوائد ملموسة لاستضافة Nuxt ذاتيًا

• مسارات خادم server/api غير محدودة، دون فوترة لكل استدعاء.
• SSR وعملية hydration الخاصة بـVue 3 تُقدَّمان من خادم Node دائم ومستقر.
• بناء Nitro قابل للنقل (node-server) سهل التعبئة في حاوية وإعادة الإنتاج.
• تخزين مؤقت للمسارات وقواعد routeRules (SSR وSSG وISR وSWR) مُتحكَّم فيها من جهة الخادم.
• توحيد عدة تطبيقات Nuxt على VPS واحد خلف Nginx.
• متغيرات بيئة وقت التشغيل (runtimeConfig) تُدار مباشرة على خادمك الخاص.
• تحكم كامل في ترويسات HTTP (CSP وHSTS وcache-control) عبر middleware في Nitro.

المتطلبات المسبقة للعتاد والبرمجيات

نشر Nuxt خطوة بخطوة

1. 01

   إعداد المشروع لـNode

   حدِّد إعداد Nitro المسبق في nuxt.config.ts:

   export default defineNuxtConfig({
     nitro: { preset: 'node-server' }
   })

   عرِّف أسرارك في runtimeConfig من جهة الخادم حصرًا — وليس في runtimeConfig.public. ومن جهة VPS، ثبّت Node.js 20 LTS عبر nvm install 20 && nvm use 20 && nvm alias default 20، ثم ثبّت PM2 بشكل عام: npm install -g pm2.

2. 02

   بناء التطبيق

   استنسخ المستودع وثبّت الاعتماديات:

   git clone https://git.yourdomain.com/your-org/your-app.git /srv/nuxt-app
   cd /srv/nuxt-app
   npm ci
   npm run build

   ينتج Nitro مجلدًا مستقلًا .output يحتوي على server/index.mjs والأصول الثابتة في .output/public. وهذا المجلد هو كل ما يحتاجه VPS لتقديم التطبيق في الإنتاج — يمكنك أيضًا تجميعه في CI ونقله عبر rsync لتجنب البناء على الخادم.

3. 03

   إنشاء ملف البيئة

   أنشئ الملف /srv/nuxt-app/.env مع متغيرات وقت التشغيل. كل متغير مسبوق بـNUXT_ يُلغي المفتاح المقابل في runtimeConfig عند بدء التشغيل:

   NUXT_MY_SECRET_KEY=production-value
   NITRO_HOST=0.0.0.0
   NITRO_PORT=3000

   لا تُدرج هذا الملف في المستودع أبدًا. تأكد من أنه مملوك للمستخدم الذي يُشغِّل PM2 وأنه قابل للقراءة من قِبَله وحده (chmod 600).

4. 04

   تشغيل خادم Nitro باستخدام PM2

   ابدأ التطبيق واضبط التشغيل التلقائي:

   pm2 start /srv/nuxt-app/.output/server/index.mjs \
     --name nuxt-app \
     --env-file /srv/nuxt-app/.env
   pm2 save
   pm2 startup

   تعرض الأمر pm2 startup سطرًا للنسخ واللصق لإنشاء خدمة systemd. نفِّذه بصلاحيات المدير. تحقَّق من أن التطبيق يعمل: يجب أن يُظهر pm2 status الحالة online.

5. 05

   إعداد Nginx كبروكسي عكسي

   أنشئ الملف /etc/nginx/sites-available/nuxt-app:

   server {
       listen 80;
       server_name yourdomain.com www.yourdomain.com;
   
       location /_nuxt/ {
           root /srv/nuxt-app/.output/public;
           expires 1y;
           add_header Cache-Control "public, immutable";
       }
   
       location /favicon.ico {
           root /srv/nuxt-app/.output/public;
       }
   
       location / {
           proxy_pass http://127.0.0.1:3000;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection 'upgrade';
           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;
           proxy_cache_bypass $http_upgrade;
       }
   }

   فعِّل الموقع واختبر الإعداد: ln -s /etc/nginx/sites-available/nuxt-app /etc/nginx/sites-enabled/ && nginx -t && systemctl reload nginx.

6. 06

   تفعيل HTTPS باستخدام Let's Encrypt

   ثبّت Certbot وإضافة Nginx، ثم أنشئ الشهادة:

   apt install certbot python3-certbot-nginx
   certbot --nginx -d yourdomain.com -d www.yourdomain.com

   يُعدِّل Certbot تلقائيًا كتلة Nginx للاستماع على المنفذ 443 وفرض إعادة التوجيه من HTTP إلى HTTPS. تحقَّق من أن X-Forwarded-Proto يُمرَّر بشكل صحيح إلى Nitro — بدونه قد يتصرف useRequestHeaders() من جهة الخادم وعمليات إعادة التوجيه القائمة على البروتوكول بشكل خاطئ. يتولى مؤقت systemd الخاص بـCertbot التجديد التلقائي، ويمكن التحقق منه بـsystemctl status certbot.timer.

7. 07

   التحديث دون انقطاع الخدمة

   للتحديث، يضمن reload في PM2 (وليس إعادة التشغيل) استمرارية الخدمة:

   cd /srv/nuxt-app
   git pull
   npm ci
   npm run build
   pm2 reload nuxt-app

   يُشغِّل PM2 الإصدار الجديد ويتحقق من استجابته ثم يُنهي القديم: صفر downtime. للتراجع، عد إلى الإيداع السابق وأعد البناء والتحميل. إذا جرى البناء في CI، انقل مجلد .output فقط عبر rsync وأعد التحميل دون إعادة البناء على الخادم.

تحسين التصيير باستخدام routeRules

‏Nitro server مقابل Docker مقابل Vercel/Netlify لاستضافة Nuxt

مرّر الجدول أفقيًا

استكشاف الأخطاء: مشكلات الإنتاج الشائعة