رایج‌ترین خطاهای اجرای Node.js روی هاست و راه‌حل آن‌ها (۵۰۲، EADDRINUSE، کمبود RAM)

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

قبل از هر چیز، لاگ را بخوانید

اولین قدم برای بررسی خطای اجرای Node.js روی هاست، خواندن لاگ زمان توقف برنامه است. در پنل میزبانی، بخش لاگ را پیدا کنید و دقت کنید که نام و مسیر این بخش به سرویس شما بستگی دارد. اگر از PM2 استفاده می‌کنید، دستور pm2 logs خروجی برنامه را نمایش می‌دهد. هنگام اجرای مستقیم نیز پیام‌ها در ترمینال دیده می‌شوند. به نخستین خطا، مسیر فایل و زمان وقوع توجه کنید. پیش از تغییر تنظیمات، مشخص کنید مشکل هنگام نصب، بیلد، شروع برنامه یا پاسخ به درخواست رخ می‌دهد.

۱. خطای 502 Bad Gateway یا 503

نمایش خطای 502 در Node.js معمولا یعنی واسط وب، مانند Nginx، نتوانسته پاسخ معتبری از اپلیکیشن بگیرد. خاموش بودن برنامه، کرش هنگام شروع یا اتصال به پورت اشتباه از علت‌های احتمالی هستند. کد ۵۰۳ نیز می‌تواند نشانه در دسترس نبودن موقت سرویس یا محدودیت ظرفیت باشد.

برای رفع این نوع خطای اجرای Node.js روی هاست، ابتدا فعال بودن پردازش و لاگ شروع برنامه را بررسی کنید. سپس پورت را با تنظیمات پنل تطبیق دهید. در محیط‌هایی که پورت از متغیر محیطی تأمین می‌شود، از process.env.PORT استفاده کنید. آدرس شنود نیز باید با معماری سرویس سازگار باشد؛ کانتینر ممکن است به 0.0.0.0 نیاز داشته باشد، اما پراکسی محلی با آدرس loopback کار کند. تأخیر طولانی پاسخ را هم بررسی کنید و توجه داشته باشید که تایم ‌اوت پراکسی معمولاً با ۵۰۴ دیده می‌شود.

۲. خطای EADDRINUSE

پیام address already in use نشان می‌دهد آدرس و پورت مورد نظر قبلا اشغال شده‌اند. ممکن است اجرای قبلی هنوز فعال باشد یا برنامه را هم از پنل و هم از ترمینال راه ‌اندازی کرده باشید.

برای پیدا کردن علت خطای اجرای Node.js روی هاست، در لینوکس و در صورت دسترسی، خروجی ss -ltnp را بررسی کنید. پس از شناسایی مالک پورت، پردازش اضافی پروژه خودتان را از مدیر پردازش متوقف کنید. انتخاب پورت تصادفی همیشه جواب نمی‌دهد و پراکسی باید به همان پورت متصل شود. برای پیشگیری از خطای EADDRINUSE، یک روش مشخص برای اجرای برنامه داشته باشید و از اجرای دستی همزمان پرهیز کنید.

بیشتر بخوانید: بهترین ارائه‌ دهندگان هاست وردپرس ایرانی و خارجی

۳. خطای JavaScript heap out of memory

اگر برنامه هنگام بیلد یا پردازش اطلاعات حجیم با پیام FATAL ERROR بسته می‌شود، احتمال رسیدن به سقف حافظه هیپ وجود دارد. نشت حافظه، کش بدون محدودیت و خواندن یک فایل بزرگ به ‌صورت یکجا از علت‌های محتمل هستند. در بررسی این خطای اجرای Node.js روی هاست، ابتدا مصرف حافظه را در طول زمان مشاهده کنید. رشد مداوم مصرف، حتی بعد از پایان درخواست‌ها، ارزش بررسی دارد. فایل‌ها را با stream پردازش کنید و نتایج پایگاه داده را صفحه ‌بندی کنید.

افزایش مقدار --max-old-space-size ممکن است موقتا کمک کند، اما رم جدیدی ایجاد نمی‌کند و کل حافظه پردازش را هم محدود نمی‌کند. برای رفع JavaScript heap out of memory، سقف را متناسب با حافظه واقعی تنظیم کنید و برای سیستم‌ عامل و سایر پردازش‌ها فضا بگذارید. اگر مصرف بهینه همچنان بالاست، منابع پلن را بازبینی کنید.

۴. خطای Cannot find module

این پیام یعنی ماژول یا فایل مورد نیاز پیدا نشده است. نصب نشدن بسته‌ها، مسیر اشتباه یا نبود خروجی بیلد می‌تواند چنین وضعیتی بسازد. در لینوکس، تفاوت حروف بزرگ و کوچک نیز مهم است زیرا فایل User.js با user.js یکسان نیست. برای رفع خطای اجرای Node.js روی هاست در این حالت، وارد پوشه دارای package.json شوید و نصب وابستگی‌ها را بررسی کنید.

اگر package-lock.json معتبر و هماهنگ دارید، npm ci نصب قابل‌تکرارتری فراهم می‌کند. برای مرحله بیلد، وابستگی‌های توسعه لازم را هم نصب کنید؛ بسته مورد نیاز زمان اجرا باید در dependencies باشد. اگر Cannot find module به فایل داخلی اشاره می‌کند، نام، مسیر و وجود فایل در خروجی نهایی را بررسی کنید.

۵. توقف برنامه بعد از بستن ترمینال یا ری ‌استارت سرور

توقف Node.js بعد از بستن ترمینال اغلب به اجرای مستقیم برنامه در نشست SSH مربوط است. اجرای موفق دستور شروع، به ‌تنهایی ماندگاری برنامه را تضمین نمی‌کند. این خطای اجرای Node.js روی هاست را با مدیر پردازش مانند PM2 یا ساز و کار اجرای دائمی پنل بررسی کنید. در سرور شخصی، بازگشت برنامه پس از ری ‌استارت نیز به تنظیم راه ‌اندازی خودکار و ذخیره فهرست پردازش‌ها نیاز دارد. برای حل توقف Node.js بعد از بستن ترمینال، راهنمای دیپلوی و مدیریت اپلیکیشن Node.js با PM2 را بخوانید زیرا در هاست مدیریت ‌شده، روش ارائه ‌دهنده اولویت دارد.

۶. خطای EACCES یا نداشتن دسترسی

این خطا معمولا از مجوز ناکافی فایل، پوشه یا عملیات شبکه ناشی می‌شود. اتصال به پورت‌های زیر ۱۰۲۴ نیز در بسیاری از محیط‌های لینوکسی به مجوز ویژه نیاز دارد. برای رفع خطای اجرای Node.js روی هاست، ابتدا مسیر یا عملیات ذکر شده در پیام را پیدا کنید. مالکیت پوشه و دسترسی کاربر اجرای برنامه را بررسی کنید و فقط مجوز لازم را بدهید. تغییر همه مجوزها به 777 راه ‌حل مناسبی نیست. برای وب ‌سرویس نیز پورت بالاتر پشت reverse proxy انتخاب بهتری است.

۷. SyntaxError یا ناسازگاری نسخه Node.js

اگر سینتکسی مثل optional chaining روی سیستم شما اجرا می‌شود، اما سرور پیام Unexpected token می‌دهد، نسخه محیط اجرا را بررسی کنید. البته هر خطای نحوی نشانه قدیمی بودن نسخه نیست و در صورتی که کد نامعتبر یا تنظیم اشتباه ماژول‌ها هم ممکن است عامل باشد. برای بررسی این خطای اجرای Node.js روی هاست، خروجی node -v را با محیط توسعه و الزامات فریم‌ ورک مقایسه کنید. نسخه پشتیبانی‌ شده را در پنل انتخاب و محدوده آن را در فیلد engines ثبت کنید.

چه زمانی مشکل از خود هاست است؟

گاهی خطای اجرای Node.js روی هاست به محدودیت‌هایی مربوط است که با اصلاح کد برطرف نمی‌شوند:

• نبود امکان اجرای پردازش دائمی یا راه ‌اندازی مجدد خودکار.
• سقف حافظه پایین‌تر از نیاز واقعی برنامه.
• پشتیبانی نکردن از نسخه سازگار Node.js.
• محدودیت پورت یا نبود امکان تنظیم اتصال پراکسی.
• نبود SSH یا ابزار معادل پنل برای نصب، بیلد و مشاهده لاگ.

اگر محدودیت‌های هاست فعلی مانع شماست، پلن‌های هاست Node.js برنت را ببینید و پیش از انتقال، سازگاری پروژه را بررسی کنید. برای مشاوره با شماره ۰۲۱۹۱۰۹۵۹۸۷ تماس بگیرید.

بیشتر بخوانید: برای پروژه Node.js چقدر RAM و CPU لازم است

چک ‌لیست پیشگیری قبل از دیپلوی

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

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

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

چرا برنامه روی لوکال اجرا می‌شود، اما روی هاست نه؟

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

چطور بفهمم مشکل از کد است یا هاست؟

یک برنامه ساده را با همان تنظیمات اجرا کنید. اگر آن کار می‌کند، بررسی پروژه را ادامه دهید و اگر اجرا نمی‌شود، تنظیمات محیط و گزارش پشتیبانی را بررسی کنید.

آیا خطای 502 در Node.js همیشه یعنی هاست مشکل دارد؟

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

کلام پایانی

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

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