استقرار Next.js روی VPS و هاست Node.js؛ آموزش مرحله‌ به‌ مرحله

مقدمه:

استقرار Next.js روی VPS و هاست Node.js به دو شکل اصلی انجام می‌شود. در سرور مجازی، نصب Node.js، مدیریت فرایند برنامه، تنظیم Nginx، SSL و امنیت سرور بر عهده شماست؛ اما در هاست Node.js بیشتر این زیرساخت از طریق کنترل‌پنل مدیریت می‌شود. در هر دو روش باید پروژه را برای محیط Production بسازید، متغیرهای محیطی را تنظیم کنید و مطمئن شوید برنامه پس از ری‌استارت سرویس همچنان اجرا می‌شود.

فهرست مطالب پیشنهادی

• پیش‌نیازهای استقرار پروژه Next.js
• مقایسه VPS و هاست Node.js
• آماده‌سازی پروژه برای انتشار
• استقرار Next.js روی VPS
• اجرای برنامه با PM2
• تنظیم Nginx، دامنه و SSL
• استقرار روی هاست Node.js
• خطاهای متداول و روش عیب‌یابی
• چک‌لیست نهایی انتشار

پیش‌نیازهای استقرار Next.js روی سرور

پیش از انتقال پروژه، ابتدا آن را در محیط محلی با حالت Production آزمایش کنید. اجرای موفق برنامه در حالت توسعه با دستور npm run dev به معنی آماده‌بودن آن برای سرور اصلی نیست.

دستورهای زیر را در مسیر پروژه اجرا کنید:

npm install
npm run build
npm run start

در پروژه‌هایی که از package-lock.json استفاده می‌کنند، دستور npm ci معمولاً برای نصب کنترل‌شده وابستگی‌ها در محیط استقرار مناسب‌تر است:

npm ci
npm run build
npm run start

در فایل package.json نیز باید اسکریپت‌های Build و Start وجود داشته باشند:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

طبق مستندات رسمی، Next.js می‌تواند به‌صورت Node.js Server، کانتینر Docker یا خروجی استاتیک مستقر شود. اجرای آن به‌صورت Node.js Server از تمام قابلیت‌های اصلی فریم‌ورک پشتیبانی می‌کند، درحالی‌که خروجی استاتیک برای قابلیت‌های وابسته به سرور محدودیت دارد. Next.js

پیش از انتشار، موارد زیر را نیز بررسی کنید:

• نسخه Node.js با نیازمندی پروژه سازگار باشد.
• اجرای npm run build بدون خطا تمام شود.
• اطلاعات محرمانه داخل مخزن Git قرار نگرفته باشد.
• فایل‌های محیطی Production آماده باشند.
• اتصال پایگاه داده از سرور مقصد امکان‌پذیر باشد.
• از کد، دیتابیس و تنظیمات فعلی نسخه پشتیبان گرفته شده باشد.

CTA اول: اگر درباره سازگاری پروژه، نسخه Node.js یا منابع موردنیاز سرور مطمئن نیستید، می‌توانید پیش از انتقال از کارشناسان شرکت تجارت الکترونیک نوژن برای بررسی زیرساخت و شیوه استقرار مشاوره دریافت کنید.

مقایسه استقرار Next.js روی VPS و هاست Node.js

انتخاب میان سرور مجازی و هاست Node.js به میزان دسترسی موردنیاز، دانش مدیریت سرور، ترافیک پروژه و ساختار برنامه بستگی دارد. هیچ‌یک از این دو گزینه برای تمام پروژه‌ها برتری مطلق ندارد.

برای یک سایت شرکتی یا پروژه‌ای که با ساختار استاندارد Next.js اجرا می‌شود، هاست Node.js می‌تواند انتخاب ساده‌ای باشد. پروژه‌ای که به Redis، صف پردازشی، WebSocket، سرویس‌های جانبی، Docker یا تنظیمات اختصاصی وب‌سرور نیاز دارد، معمولاً روی VPS انعطاف بیشتری خواهد داشت.

[لینک داخلی پیشنهادی: انکرتکست «خرید سرور مجازی مناسب برنامه‌نویسی» ← صفحه خدمات سرور مجازی]

[لینک داخلی پیشنهادی: انکرتکست «راهنمای انتخاب منابع VPS» ← مقاله انتخاب RAM و CPU سرور مجازی]

CTA دوم: برای مشاهده زیرساخت‌های قابل‌استفاده در پروژه‌های Node.js می‌توانید سرویس‌های سرور مجازی شرکت تجارت الکترونیک نوژن را بررسی کنید. انتخاب نهایی بهتر است براساس مصرف RAM، پردازنده، فضای ذخیره‌سازی، ترافیک و سرویس‌های جانبی پروژه انجام شود.

آماده‌سازی پروژه Next.js برای استقرار

تنظیم متغیرهای محیطی

اطلاعاتی مانند آدرس دیتابیس، کلید سرویس‌ها و توکن‌ها را مستقیماً داخل کد قرار ندهید. این مقادیر باید از طریق متغیرهای محیطی سرور یا بخش Environment Variables کنترل‌پنل تعریف شوند.

نمونه فایل:

NODE_ENV=production
DATABASE_URL=your_database_connection
NEXT_PUBLIC_API_URL=https://example.com/api

متغیرهایی که با NEXT_PUBLIC_ شروع می‌شوند ممکن است در کد سمت مرورگر قرار بگیرند؛ بنابراین رمز عبور، کلید خصوصی یا توکن محرمانه نباید با این پیشوند تعریف شود.

همچنین توجه کنید که تغییر برخی متغیرهای محیطی به اجرای مجدد Build نیاز دارد. پس از اصلاح آن‌ها، پروژه را دوباره بسازید و فرایند برنامه را ری‌استارت کنید.

بررسی وابستگی‌ها

وابستگی‌های موردنیاز محیط اجرا باید در بخش dependencies فایل package.json باشند. قرارگرفتن یک بسته ضروری فقط در devDependencies می‌تواند باعث خطا در سروری شود که وابستگی‌های توسعه را نصب نمی‌کند.

همچنین بهتر است فایل قفل پکیج مانند package-lock.json همراه پروژه نگهداری شود تا نسخه وابستگی‌ها بین محیط توسعه و سرور کنترل‌پذیرتر باشد.

بررسی نوع رندر

پیش از انتخاب هاست مشخص کنید پروژه از کدام قابلیت‌ها استفاده می‌کند:

• صفحات استاتیک
• رندر سمت سرور
• Route Handler یا API Route
• Server Action
• بهینه‌سازی تصویر
• بازتولید دوره‌ای صفحات
• اتصال مستقیم به پایگاه داده

اگر پروژه کاملاً استاتیک باشد، ممکن است به اجرای دائمی Node.js نیاز نداشته باشد. اما قابلیت‌هایی مانند رندر سمت سرور و API داخلی معمولاً به یک محیط اجرای Node.js احتیاج دارند.

آموزش استقرار Next.js روی VPS

این آموزش بر مبنای یک سرور لینوکسی ارائه شده است. نام بسته‌ها و بعضی مسیرها ممکن است میان توزیع‌های مختلف تفاوت داشته باشد.

مرحله اول: آماده‌سازی امن سرور

با یک کاربر دارای دسترسی مدیریتی وارد سرور شوید. استفاده دائمی از حساب Root برای اجرای برنامه پیشنهاد نمی‌شود.

سیستم‌عامل را به‌روزرسانی و ابزارهای ضروری را نصب کنید. سپس Node.js را از روش رسمی و متناسب با توزیع خود نصب کنید. بهتر است نسخه پشتیبانی‌شده‌ای را انتخاب کنید که با نسخه Next.js پروژه سازگار باشد.

پس از نصب، وضعیت را بررسی کنید:

node --version
npm --version

دسترسی SSH، فایروال و کاربران سرور باید قبل از انتشار برنامه بررسی شوند. پورت داخلی برنامه را بدون نیاز مستقیماً برای اینترنت باز نکنید؛ در معماری رایج، Nginx درخواست‌های عمومی را به برنامه‌ای که روی یک پورت محلی اجرا می‌شود منتقل می‌کند.

[لینک داخلی پیشنهادی: انکرتکست «کارهای ضروری بعد از خرید VPS اوبونتو» ← مقاله تنظیمات اولیه و امنیت سرور]

مرحله دوم: انتقال پروژه

می‌توانید پروژه را از مخزن Git دریافت کنید:

cd /var/www
sudo git clone YOUR_REPOSITORY_URL next-app
sudo chown -R $USER:$USER /var/www/next-app
cd /var/www/next-app

آدرس واقعی مخزن را جایگزین YOUR_REPOSITORY_URL کنید. اگر مخزن خصوصی است، از کلید استقرار با حداقل سطح دسترسی استفاده کنید و کلید شخصی روزمره خود را روی سرور کپی نکنید.

روش دیگر، انتقال فایل‌ها با SFTP یا ابزار استقرار خودکار است. در این حالت پوشه‌هایی مانند node_modules و .next را از رایانه شخصی منتقل نکنید؛ وابستگی‌ها و خروجی Build باید متناسب با محیط سرور ساخته شوند.

مرحله سوم: نصب و ساخت نسخه Production

در مسیر پروژه اجرا کنید:

npm ci
npm run build

اگر Build شکست خورد، ابتدا متن کامل خطا را بررسی کنید. کمبود حافظه، نسخه ناسازگار Node.js، متغیر محیطی تعریف‌نشده و خطای TypeScript از دلایل رایج شکست Build هستند.

بعد از ساخت موفق، برنامه را آزمایشی اجرا کنید:

npm run start

پورت پیش‌فرض یا پورت تعیین‌شده پروژه باید فقط از داخل سرور آزمایش شود:

curl http://127.0.0.1:3000

اگر پاسخ دریافت شد، اجرای اصلی برنامه آماده تنظیم است.

اجرای دائمی Next.js با PM2

اجرای برنامه در ترمینال معمولی با قطع اتصال SSH متوقف می‌شود. یک مدیر فرایند مانند PM2 می‌تواند برنامه را در پس‌زمینه اجرا کند، لاگ‌ها را نمایش دهد و برای راه‌اندازی مجدد فرایند پس از بوت سرور پیکربندی شود.

PM2 را نصب و برنامه را اجرا کنید:

sudo npm install -g pm2
cd /var/www/next-app
pm2 start npm --name "next-app" -- start
pm2 status

برای مشاهده لاگ‌ها:

pm2 logs next-app

پس از اطمینان از اجرای صحیح:

pm2 save
pm2 startup

دستور pm2 startup فرمانی متناسب با سیستم‌عامل نمایش می‌دهد. همان فرمان خروجی را با سطح دسترسی لازم اجرا و سپس دوباره pm2 save را بررسی کنید. مستندات PM2 نیز استفاده از فهرست فرایندها، لاگ‌ها، ذخیره وضعیت و Startup Hook را برای مدیریت برنامه توضیح می‌دهد. Quick Start

در محیط عملیاتی، برنامه را با حساب کاربری مخصوص اجرا کنید. اجرای برنامه با Root دامنه اثر یک آسیب‌پذیری احتمالی را افزایش می‌دهد.

تنظیم Nginx برای اتصال دامنه

Nginx می‌تواند درخواست دامنه را دریافت و به برنامه Next.js روی پورت داخلی هدایت کند. نمونه پایه زیر را متناسب با دامنه خود تغییر دهید:

server {
    listen 80;
    listen [::]:80;

    server_name example.com www.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        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;
    }
}

مستندات Nginx نیز برای ساخت Reverse Proxy از قرار دادن proxy_pass در بلوک location و مشخص‌کردن آدرس سرویس مقصد استفاده می‌کند. nginx.org

پس از ذخیره تنظیمات، صحت پیکربندی را بررسی کنید:

sudo nginx -t

فقط در صورت موفق‌بودن تست، Nginx را Reload کنید:

sudo systemctl reload nginx

رکوردهای DNS دامنه باید به IP سرور اشاره کنند. بعد از انتشار صحیح DNS و بازشدن سایت از طریق HTTP، گواهی SSL را با ابزار موردتأیید توزیع لینوکس یا سرویس‌دهنده فعال کنید.

[لینک داخلی پیشنهادی: انکرتکست «آموزش تنظیم DNS دامنه» ← مقاله تنظیم رکوردهای DNS]

[لینک داخلی پیشنهادی: انکرتکست «نصب و تمدید گواهی SSL» ← مقاله آموزش SSL و HTTPS]

استقرار Next.js روی هاست Node.js

جزئیات پنل‌ها یکسان نیست، اما مسیر کلی معمولاً شامل مراحل زیر است:

مرحله اول: ساخت برنامه Node.js

در کنترل‌پنل، یک برنامه Node.js ایجاد و موارد زیر را مشخص کنید:

• دامنه یا زیردامنه
• مسیر اصلی پروژه
• نسخه Node.js سازگار
• حالت Production
• متغیرهای محیطی
• فرمان Build
• فرمان Start
• پورت داخلی برنامه

اگر پنل اجازه انتخاب فرمان‌ها را بدهد، ساختار معمول چنین است:

npm ci
npm run build
npm run start

در بعضی سرویس‌ها Build باید از طریق Terminal اجرا شود و در برخی دیگر هنگام انتشار به‌صورت خودکار انجام می‌شود.

مرحله دوم: انتقال فایل‌ها

فایل‌های پروژه را با Git، File Manager یا SFTP منتقل کنید. فایل‌های محرمانه نباید همراه مخزن عمومی بارگذاری شوند؛ آن‌ها را در بخش Environment Variables پنل ثبت کنید.

پس از انتقال، وابستگی‌ها را نصب و Build را اجرا کنید. اگر هاست محدودیت حافظه یا زمان اجرای دستور داشته باشد، ممکن است Build پروژه‌های سنگین متوقف شود. در چنین شرایطی باید محدودیت سرویس بررسی شود، نه اینکه فرایند Build بدون تشخیص علت مرتب تکرار شود.

مرحله سوم: تنظیم فرمان اجرا

فرمان معمول اجرای نسخه Production برابر است با:

npm run start

برنامه باید از پورتی استفاده کند که هاست در اختیار آن قرار می‌دهد. مقدار پورت را ثابت و دلخواه انتخاب نکنید، مگر ارائه‌دهنده چنین اجازه‌ای داده باشد.

پس از راه‌اندازی، از بخش لاگ‌ها پاسخ برنامه، خطاهای اتصال دیتابیس و متغیرهای محیطی را بررسی کنید. سپس دامنه و SSL را از داخل پنل فعال کنید.

استفاده از خروجی Standalone

برای کاهش فایل‌های لازم در محیط اجرا می‌توان از خروجی Standalone استفاده کرد:

// next.config.js
const nextConfig = {
  output: 'standalone'
}

module.exports = nextConfig

پس از Build، Next.js پوشه‌ای شامل فایل‌های ضروری اجرای برنامه تولید می‌کند. بااین‌حال، پوشه‌های public و فایل‌های استاتیک موردنیاز باید مطابق مستندات و ساختار انتشار پروژه در کنار خروجی قرار گیرند.

این روش برای کانتینرها و استقرارهایی که به بسته اجرایی کوچک‌تر نیاز دارند مفید است، اما استفاده از آن اجباری نیست. پیش از جایگزین‌کردن روش فعلی، خروجی را در محیط آزمایشی بررسی کنید.

خطاهای متداول هنگام استقرار

خطای Module not found

ابتدا نصب وابستگی‌ها و محل قرارگیری بسته در dependencies را بررسی کنید. تفاوت حروف بزرگ و کوچک در نام فایل‌ها نیز روی لینوکس اهمیت دارد.

خطای Port already in use

فرایند دیگری پورت برنامه را اشغال کرده است. وضعیت PM2 یا فرایندهای درحال اجرا را بررسی کنید و بدون شناسایی فرایند، آن را متوقف نکنید.

خطای 502 Bad Gateway

این خطا معمولاً یعنی Nginx نمی‌تواند به برنامه مقصد متصل شود. وضعیت PM2، پورت برنامه، آدرس proxy_pass و لاگ‌های Nginx را بررسی کنید.

اجراشدن سایت بدون CSS یا تصاویر

پوشه public، فایل‌های .next/static، مسیرهای Base Path و تنظیمات Reverse Proxy را بررسی کنید. این مشکل در خروجی Standalone ممکن است به‌دلیل انتقال‌نیافتن فایل‌های استاتیک رخ دهد.

خطای دیتابیس

آدرس اتصال، فایروال، مجوز کاربر دیتابیس، گواهی TLS و امکان دسترسی از IP سرور را کنترل کنید. اطلاعات اتصال را در لاگ عمومی نمایش ندهید.

توقف برنامه بعد از خروج از SSH

برنامه احتمالاً مستقیماً در Shell اجرا شده است. آن را با PM2، systemd یا راهکار مدیریت‌شده سرویس‌دهنده اجرا کنید.

چک‌لیست نهایی انتشار

• از پروژه و دیتابیس نسخه پشتیبان تهیه شده است.
• نسخه Node.js با پروژه سازگار است.
• npm ci بدون خطا اجرا شده است.
• npm run build با موفقیت پایان یافته است.
• متغیرهای محیطی Production تنظیم شده‌اند.
• برنامه با کاربر محدود و غیر Root اجرا می‌شود.
• PM2 یا مدیر فرایند دیگری فعال است.
• Nginx فقط به پورت داخلی برنامه متصل است.
• DNS دامنه به سرور صحیح اشاره می‌کند.
• HTTPS فعال و تمدید گواهی بررسی شده است.
• لاگ برنامه و وب‌سرور قابل‌دسترسی است.
• فرایند بازیابی نسخه پشتیبان آزمایش شده است.

جمع‌بندی

استقرار Next.js روی VPS و هاست Node.js در اصل شامل نصب وابستگی‌ها، تعریف تنظیمات محیطی، اجرای Build و راه‌اندازی برنامه در حالت Production است. تفاوت اصلی این دو روش در میزان کنترل و مسئولیت مدیریت زیرساخت دیده می‌شود.

هاست Node.js برای پروژه‌ای با ساختار استاندارد و نیاز مدیریتی کمتر مناسب است. سرور مجازی برای پروژه‌هایی که به تنظیمات اختصاصی، سرویس‌های جانبی، دسترسی سیستمی یا امکان توسعه زیرساخت نیاز دارند، انعطاف بیشتری ایجاد می‌کند.

در استقرار روی VPS، اجرای برنامه با مدیر فرایند، قراردادن Nginx در مقابل Node.js، محدودکردن دسترسی‌ها، فعال‌سازی SSL و نگهداری نسخه پشتیبان بخش‌های ضروری کار هستند. انتخاب منابع نیز باید براساس نتیجه Build، مصرف واقعی برنامه، تعداد درخواست‌ها و سرویس‌های همراه انجام شود.

CTA سوم: اگر برای استقرار پروژه، انتقال از هاست فعلی یا انتخاب سرور مجازی مناسب به بررسی فنی نیاز دارید، می‌توانید با شرکت تجارت الکترونیک نوژن تماس بگیرید و سرویس‌های میزبانی و پشتیبانی زیرساخت را متناسب با پروژه خود بررسی کنید.

سؤالات متداول

آیا Next.js روی هاست معمولی اجرا می‌شود؟

اگر پروژه خروجی کاملاً استاتیک داشته باشد، امکان میزبانی آن روی هاست استاتیک وجود دارد. برای رندر سمت سرور، API داخلی و قابلیت‌های وابسته به سرور، هاست باید از اجرای Node.js پشتیبانی کند.

برای Next.js هاست Node.js بهتر است یا VPS؟

برای پروژه‌های استاندارد و مدیریت ساده‌تر، هاست Node.js مناسب است. VPS برای تنظیمات اختصاصی، سرویس‌های جانبی و دسترسی بیشتر انتخاب انعطاف‌پذیرتری محسوب می‌شود.

آیا اجرای npm run dev روی سرور صحیح است؟

خیر. این فرمان برای توسعه طراحی شده است. در محیط Production ابتدا npm run build و سپس npm run start را اجرا کنید.

آیا برای اجرای Next.js به Nginx نیاز داریم؟

اجباری نیست، اما در VPS استفاده از Reverse Proxy برای اتصال دامنه، مدیریت HTTPS و هدایت درخواست‌ها به پورت داخلی برنامه کاربردی است.

چگونه Next.js را بعد از ری‌استارت سرور فعال نگه داریم؟

می‌توانید از PM2، systemd یا کانتینر استفاده کنید. در PM2 باید Startup Hook و ذخیره فهرست فرایندها به‌درستی تنظیم شود.

چرا هنگام Build حافظه سرور پر می‌شود؟

فرایند Build ممکن است نسبت به اجرای عادی برنامه منابع بیشتری مصرف کند. ابتدا وابستگی‌ها، خطاهای Build و مصرف حافظه را بررسی کنید؛ سپس در صورت نیاز منابع سرور یا روش Build را تغییر دهید.

آیا انتقال پوشه node_modules به سرور کافی است؟

خیر. وابستگی‌ها بهتر است روی محیط مقصد و براساس فایل قفل پکیج نصب شوند تا با سیستم‌عامل و معماری سرور سازگار باشند.