نحوه پیکربندی فایل .env در Next.js و Node.js | آموزش Environment Variables

تقریباً در تمام پروژه‌های مدرن جاوااسکریپت، اطلاعاتی مانند رمز عبور دیتابیس، کلیدهای API، تنظیمات سرویس‌های خارجی و مسیرهای ذخیره‌سازی نباید مستقیماً داخل کد نوشته شوند. بهترین راه برای مدیریت این اطلاعات، استفاده از Environment Variables و فایل‌های env. است.

در این مقاله با نحوه استفاده از فایل‌های env. در Next.js و Node.js آشنا می‌شویم، تفاوت انواع فایل‌های محیطی را بررسی می‌کنیم و بهترین روش‌های امنیتی را یاد می‌گیریم.

فایل env. چیست؟

فایل env. یک فایل متنی ساده است که شامل مجموعه‌ای از متغیرهای محیطی (Environment Variables) است. این متغیرها به برنامه اجازه می‌دهند بدون تغییر کد، تنظیمات مختلف را مدیریت کند.

DATABASE_URL=postgres://postgres:password@localhost:5432/blog
JWT_SECRET=my-secret-key
API_KEY=123456789
UPLOAD_DIR=uploads

هر خط شامل یک کلید و مقدار است که برنامه در زمان اجرا آن را از طریق process.env می‌خواند.

چرا باید از فایل env. استفاده کنیم؟

فرض کنید اطلاعات اتصال به دیتابیس را مستقیماً داخل کد بنویسید:

const db = connect({
  host: "localhost",
  user: "admin",
  password: "123456",
});

این روش مشکلات زیادی ایجاد می‌کند:

• اطلاعات حساس داخل مخزن Git ذخیره می‌شود.
• تغییر رمز عبور نیازمند تغییر کد است.
• برای هر محیط باید فایل‌ها را ویرایش کنید.
• احتمال نشت اطلاعات افزایش پیدا می‌کند.

در مقابل، استفاده از فایل env. این مشکلات را برطرف می‌کند.

DB_HOST=localhost
DB_USER=admin
DB_PASSWORD=123456

و در کد:

const host = process.env.DB_HOST;
const user = process.env.DB_USER;
const password = process.env.DB_PASSWORD;

ساخت فایل env.

در ریشه پروژه فایل زیر را ایجاد کنید:

.env

سپس مقادیر مورد نیاز را داخل آن قرار دهید:

DATABASE_URL=postgres://localhost:5432/mydb
JWT_SECRET=super-secret-key
UPLOAD_DIR=uploads
API_URL=https://api.example.com

استفاده در Node.js

در نسخه‌های جدید Node.js متغیرهای محیطی به راحتی قابل استفاده هستند:

console.log(process.env.DATABASE_URL);

اگر از پروژه‌ای استفاده می‌کنید که نیاز به پکیج dotenv دارد:

npm install dotenv

سپس:

import dotenv from "dotenv";

dotenv.config();

console.log(process.env.JWT_SECRET);

استفاده از فایل env. در Next.js

در Next.js نیازی به نصب پکیج dotenv نیست. این فریم‌ورک به صورت پیش‌فرض فایل‌های محیطی را بارگذاری می‌کند.

const db = process.env.DATABASE_URL;

این متغیرها در Server Components، Route Handlers و Server Actions در دسترس هستند.

تفاوت فایل‌های مختلف Environment

• env. → تنظیمات عمومی پروژه
• env.local. → تنظیمات مخصوص سیستم توسعه‌دهنده
• env.development. → فقط هنگام اجرای پروژه در حالت Development
• env.production. → مخصوص محیط Production
• env.test. → برای تست‌های خودکار

تفاوت NEXT_PUBLIC

به صورت پیش‌فرض تمام متغیرهای محیطی فقط در سمت سرور قابل دسترسی هستند.

API_URL=https://api.example.com

اما اگر بخواهید مقدار در سمت مرورگر نیز قابل استفاده باشد باید از پیشوند NEXT_PUBLIC استفاده کنید.

NEXT_PUBLIC_API_URL=https://api.example.com

و سپس:

const api = process.env.NEXT_PUBLIC_API_URL;

چه اطلاعاتی را نباید Public کنیم؟

هرگز اطلاعات زیر را با NEXT_PUBLIC منتشر نکنید:

• JWT Secret
• رمز عبور دیتابیس
• کلیدهای خصوصی API
• SMTP Password
• OAuth Secret
• توکن‌های خصوصی

هر متغیری که با NEXT_PUBLIC شروع شود داخل فایل‌های JavaScript مرورگر قرار می‌گیرد و برای همه کاربران قابل مشاهده خواهد بود.

استفاده از env. برای مدیریت مسیر آپلود فایل‌ها

فرض کنید تصاویر کاربران داخل پوشه‌ای به نام uploads ذخیره می‌شوند.

UPLOAD_DIR=uploads

سپس در پروژه:

const uploadDir =
  process.env.UPLOAD_DIR ??
  path.join(process.cwd(), "uploads");

به این ترتیب اگر مسیر ذخیره‌سازی تغییر کند، کافی است مقدار فایل env. را تغییر دهید.

استفاده برای اتصال دیتابیس

DATABASE_URL=postgres://postgres:password@localhost:5432/blog

const db = drizzle(process.env.DATABASE_URL!);

استفاده برای APIهای خارجی

API_URL=https://api.example.com

const response = await fetch(
  process.env.API_URL + "/posts"
);

بهترین روش‌های امنیتی

• هرگز فایل env.local. را داخل Git قرار ندهید.
• از رمزها و Secretهای قوی استفاده کنید.
• برای Development و Production فایل‌های جداگانه داشته باشید.
• هیچ‌گاه اطلاعات حساس را با NEXT_PUBLIC منتشر نکنید.
• پس از تغییر فایل env.، سرور را مجدداً راه‌اندازی کنید.

اشتباهات رایج

قرار دادن فاصله اضافی

اشتباه:

API_KEY = abc

صحیح:

API_KEY=abc

فراموش کردن Restart سرور

پس از هر تغییری در فایل‌های env. باید سرور را مجدداً اجرا کنید.

npm run dev

جمع‌بندی

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

اگر در پروژه‌های Next.js یا Node.js فعالیت می‌کنید، آشنایی کامل با Environment Variables یکی از مهارت‌های ضروری برای توسعه نرم‌افزارهای حرفه‌ای محسوب می‌شود.