پرش به مطلب اصلی

محیط اجرای Node.js

ابرکلیک از استقرار و اجرای پروژه‌های Node.js با شناسایی خودکار نوع پکیج‌منیجر و سیستم بیلد، پشتیبانی می‌کند. بدون نیاز به تعریف فایل Dockerfile، بیلدپکِ ابرکلیک پروژه شما را تحلیل کرده و آماده اجرا می‌کند.

▶
ویدیو: استقرار اپ Node.jsplaceholder — ویدیو را اینجا جایگزین کنید

نسخه‌ها و ابزارهای پشتیبانی‌شده​

  • نسخه‌های Node.js: نسخه از فیلد engines.node در package.json یا فایل .nvmrc خوانده می‌شود.
  • مدیریت پکیج‌ها: پشتیبانی بومی از ابزارهای npm، yarn و pnpm.

شروع سریع (Quick Start)​

۱. ساخت برنامه ساده اکسپرس (Express)​

یک فولدر جدید بسازید و پروژه را مقداردهی اولیه کنید:

mkdir my-node-app && cd my-node-app
npm init -y
npm install express

فایل اصلی برنامه (index.js) را با محتوای ساده زیر ایجاد کنید:

const express = require('express');
const app = express();
// بسیار مهم: پورت باید پویا و از متغیر محیطی خوانده شود
const PORT = process.env.PORT || 3000;

app.get('/', (req, res) => {
  res.send('سلام از دنیای Node.js روی پلتفرم ابرکلیک!');
});

app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

۲. تعریف اسکریپت استارت (Start Script)​

مطمئن شوید که در فایل package.json بخش scripts حاوی دستور استارت باشد:

{
  "scripts": {
    "start": "node index.js"
  }
}

۳. ساخت فایل قفل (Lockfile)​

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

npm install --package-lock-only

۴. استقرار برنامه​

با اجرای دستور زیر، فرآیند آپلود کدها و دیپلوی بلافاصله آغاز می‌شود:

abrclick deploy --app my-node-app

منطق شناسایی پروژه (Buildpack Detection)​

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

  1. فایل package.json در ریشه پروژه شما وجود داشته باشد.
  2. یکی از فایل‌های package-lock.json (برای npm)، yarn.lock (برای yarn) یا pnpm-lock.yaml (برای pnpm) در ریشه باشد.
  3. هیچ فایل Dockerfile در ریشه پروژه وجود نداشته باشد (زیرا وجود Dockerfile اولویت بالاتری دارد).

پیکربندی‌های پیشرفته (Configuration)​

انتخاب خودکار مدیریت پکیج‌ها​

ابرکلیک بر اساس فایل قفل موجود در ریشه، پکیج‌منیجر مناسب را با دستور بهینه آن برای نصب وابستگی‌ها انتخاب می‌کند:

فایل قفلابزار مدیریتدستور نصب پیش‌فرض
package-lock.jsonnpmnpm ci
yarn.lockyarnyarn install --frozen-lockfile
pnpm-lock.yamlpnpmpnpm install --frozen-lockfile

تعیین نسخه Node.js​

شما می‌توانید نسخه مورد نظر خود را در فیلد engines فایل package.json تعریف کنید تا لایسنس بیلدپک آن نسخه را برای شما لود کند:

{
  "engines": {
    "node": "22.x",
    "npm": "10.x"
  }
}

همچنین سیستم از فایل .nvmrc در ریشه پروژه نیز پشتیبانی می‌کند:

22.5.0

فرآیند بیلد و کامپایل کدهای منبع​

اگر پروژه شما نیاز به گام کامپایل (مانند پروژه‌های TypeScript) داشته باشد، کافی است اسکریپت build را در فایل package.json معرفی کنید:

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

سیستم به‌صورت خودکار: ۱. ابتدا متد npm run build را اجرا کرده و خروجی‌های پوشه دیست را تولید می‌کند. ۲. در مرحله زمان اجرا دستور npm start را برای اجرای برنامه زنده شما به کار می‌برد.

پورت گوش دادن (Port Binding)​

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

const PORT = process.env.PORT || 3000;
app.listen(PORT);

مشاهده لاگ‌ها​

برای بررسی لاگ‌های برنامه Node.js خود، از دستور زیر استفاده کنید:

abrclick logs <app>

این دستور لاگ‌های زمان اجرا (runtime) را به‌صورت زنده نمایش می‌دهد. لاگ‌های بیلد نیز در حین اجرای abrclick deploy به‌صورت خودکار استریم می‌شوند.

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

نکته فنی

در برنامه‌های سالم Node.js، معمولاً پیام شروع سرور مانند Server listening on :3000 یا Server is running on port 3000 را در لاگ خواهید دید. اگر این پیام را مشاهده نکردید، احتمالاً برنامه در حال راه‌اندازی گیر کرده است.

برای اطلاعات بیشتر درباره مدیریت لاگ‌ها، راهنمای کامل لاگ‌ها را مطالعه کنید.

رفع خطاهای رایج​

اپ بالا نمی‌آید / crash loop​

علت: رایج‌ترین دلیل این است که برنامه بر روی پورت اشتباه یا آدرس 127.0.0.1 گوش می‌دهد. پلتفرم ترافیک را به پورت تزریق‌شده در process.env.PORT هدایت می‌کند و اگر برنامه شما روی پورت دیگری اجرا شود یا فقط روی localhost گوش بدهد، درخواست‌ها دریافت نمی‌شوند.

راه‌حل: مطمئن شوید برنامه شما حتماً بر روی process.env.PORT و آدرس 0.0.0.0 یا بدون تعیین host (که به‌طور پیش‌فرض روی تمام آدرس‌ها گوش می‌دهد) اجرا می‌شود:

const PORT = process.env.PORT || 3000;
app.listen(PORT, '0.0.0.0', () => {
  console.log(`Server listening on port ${PORT}`);
});

اسکریپت start پیدا نشد​

علت: فایل package.json شما فاقد فیلد start در بخش scripts است. بیلدپک ابرکلیک برای اجرای برنامه به دنبال این اسکریپت می‌گردد.

راه‌حل: اسکریپت start را به فایل package.json خود اضافه کنید:

{
  "scripts": {
    "start": "node index.js"
  }
}

نسخه Node.js اشتباه​

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

راه‌حل: نسخه Node.js مورد نظر خود را در فایل package.json یا .nvmrc مشخص کنید:

{
  "engines": {
    "node": "22.x"
  }
}

یا در فایل .nvmrc:

22.5.0

بیلد ناموفق / نصب وابستگی‌ها با خطا مواجه شد​

علت: معمولاً به دلیل عدم وجود فایل قفل (lockfile) یا ناسازگاری نسخه‌های وابستگی‌ها رخ می‌دهد. در محیط بیلد ابرکلیک، اینترنت عمومی در دسترس نیست و آینه داخلی (internal mirror) به‌صورت خودکار استفاده می‌شود.

راه‌حل: مطمئن شوید فایل قفل مناسب (مثلاً package-lock.json برای npm، yarn.lock برای yarn یا pnpm-lock.yaml برای pnpm) را در پروژه خود کامیت کرده‌اید. سپس دوباره deploy کنید.

OOMKilled / خطای حافظه​

علت: برنامه شما از حافظه بیشتر از محدودیت تعریف‌شده (پیش‌فرض ۵۱۲Mi) استفاده کرده است و کوبرنتیز پاد را متوقف کرده است.

راه‌حل: محدودیت حافظه برنامه خود را از طریق داشبورد یا تغییر پلن افزایش دهید. همچنین می‌توانید استفاده از حافظه در کد خود را بررسی و بهینه‌سازی کنید.