متغیرهای محیطی Node.js؛ جداسازی تنظیمات و اعتبارسنجی امن

در Node.js، متغیرهای محیطی از طریق process.env در دسترس‌اند و مقدارشان معمولاً رشته است. جداسازی تنظیمات از کد کافی نیست؛ باید نبودن مقدار، نوع و محدودهٔ آن هم بررسی شود. این راهنما اعتبارسنجیِ تنظیمات را با نمونهٔ محلی نشان می‌دهد، بدون چاپ رمز یا تغییر اپلیکیشن زنده.

۱. چه چیزی تنظیم است و چه چیزی راز؟

NODE_ENV=production خودکار برای همهٔ کتابخانه‌ها تنظیم مناسب نمی‌سازد؛ هر نرم‌افزار رفتار خودش را دارد. نام و مقدار تنظیمات development، staging و production باید جدا و مستند باشند. مقدار نمونه را با اطلاعات واقعی حساب جایگزین نکنید مگر در مسیر امن تنظیم همان برنامه.

۲. اعتبارسنجی قبل از شروع کار اصلی

فایل آموزشی env-check.cjs یک تنظیم غیرحساس را می‌خواند. این فایل را در پوشهٔ آزمایش مستقل ذخیره کنید؛ نام متغیر مخصوص نمونه است و به تنظیمات حساب شما دست نمی‌زند:

const raw = process.env.ARTICLE_DEMO_LIMIT;
if (raw === undefined || !/^[0-9]+$/.test(raw)) {
  console.error("ARTICLE_DEMO_LIMIT must be an integer");
  process.exitCode = 1;
} else {
  const limit = Number(raw);
  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) {
    console.error("ARTICLE_DEMO_LIMIT out of range");
    process.exitCode = 1;
  } else {
    console.log(JSON.stringify({ limit }));
  }
}

الگو فقط رقم می‌پذیرد؛ Number.isSafeInteger و بازه هم بعد از تبدیل بررسی می‌شوند. از parseInt به‌عنوان اعتبارسنجی کامل استفاده نشده، چون ورودی‌هایی مانند 12x می‌توانند بخشی معتبر داشته باشند.

۳. اجرای محلی و تفسیر نتیجه

ARTICLE_DEMO_LIMIT=12 node env-check.cjs

خط بالا برای شِل‌های POSIX است. در PowerShell، متغیر را برای فرایند آزمایشی تنظیم می‌کنید و سپس node env-check.cjs را اجرا می‌کنید؛ نحو دو محیط را یکی نگیرید. در آزمون واقعیِ این مقاله مقدار۱۲ پذیرفته و خروجی {“limit”:۱۲} تولید شد؛ 12x پیام integer و ۱۰۱ پیام out of range با وضعیت خروج۱ داد.

نکته: تنها مقدار غیرحساسِ limit در خروجی نمونه چاپ می‌شود. برای متغیرهای راز، فقط نام تنظیمِ مفقود یا نتیجهٔ اعتبارسنجی را ثبت کنید؛ هرگز console.log(process.env) نگذارید.

۴. فایل env چگونه وارد فرایند می‌شود؟

وجود فایل .env به‌تنهایی به معنی بارگذاری آن توسط هر برنامه نیست. Node.js در شاخه‌های جدید قابلیت‌هایی مانند –env-file و process.loadEnvFile دارد؛ چارچوب‌ها هم ممکن است قواعد جدا داشته باشند. نسخه و روش واقعی برنامه را بررسی کنید، نه اینکه صرفاً فایل را کنار کد قرار دهید.

مقادیر .env در Node به رشته تفسیر می‌شوند؛ “false” یک رشتهٔ غیرخالی است و Boolean آن true می‌شود. برای گزینهٔ روشن/خاموش، مقادیر مجاز را صریح مقایسه کنید. همچنین ترتیب بارگذاری و اولویت مقدار موجودِ فرایند مهم است؛ تنظیم پنل و فایل نباید بدون تصمیم روشن همدیگر را بپوشانند.

۵. کنترل‌ها پیش از انتقال به هاست

• فهرست نام متغیرهای لازم بدون مقادیر محرمانه آماده است.
• فایل نمونه فقط placeholder و تنظیم غیرحساس دارد.
• اسرار در بستهٔ عمومی فرانت‌اند یا فایل قابل دانلود نیستند.
• مقادیر staging به سرویس واقعی پرداخت و ایمیل وصل نمی‌شوند.
• تغییر تنظیم و restart احتمالی در طرح استقرار جدا بررسی می‌شود.

در تنظیمات پنل، مقدار را در فیلد مربوط و مسیر مجاز وارد می‌کنند؛ اسکرین‌شات آن باید موضعی محو شود. این مقاله نصب یا restart روی هاست انجام نمی‌دهد؛ راهنمای موجود راه‌اندازی برنامه، محل کلی مدیریت اپلیکیشن را توضیح می‌دهد.

۶. نشانهٔ آمادگی

برنامه باید با تنظیم معتبر وارد مسیر اصلی شود و با تنظیم ضروریِ نامعتبر، پیام روشن و بدون مقدار راز بدهد. این آزمون، اتصال واقعی دیتابیس یا درستی استقرار را ثابت نمی‌کند؛ فقط قرارداد تنظیمات را کنترل می‌کند. پیش از استفاده در تولید، همین قرارداد با ورودی‌های واقعیِ امن و محیط مقصد بررسی شود.

۷. مسیر مطالعهٔ مرتبط

• راه‌اندازی اپلیکیشن Node.js و پایتون روی هاست
• استقرار پروژه‌ی Next.js ساخته‌شده با دستیار کدنویسی روی هاست Node.js

۸. منابع و روش بررسی

منابع رسمی در ۲۴ اکتبر ۲۰۲۶ بررسی شدند. مثال‌های کدِ این متن در Node.js نسخهٔ ۲۴.۱۹.۰ روی محیط محلی ایزوله بررسی شده‌اند؛ نصب روی هاست، اتصال دیتابیس یا کارایی تولید با این آزمایش اثبات نشده است.

• Node.js: متغیرهای محیطی در شاخهٔ ۲۴
• Node.js: فرایند و process.env در شاخهٔ ۲۴