مدیریت متغیرهای محیطی در Next.js
حدود ۵ دقیقه مطالعه
وقتی روی یک پروژه بزرگ یا حتی یک وب‌سایت شخصی کار می‌کنید، اطلاعات حساسی مثل کلیدهای API (API Keys)، آدرس دیتابیس‌ها و رمزهای عبور وجود دارن که به هیچ وجه نباید به صورت مستقیم (Hard-code) داخل کدهای شما قرار بگیرن. قرار دادن این اطلاعات داخل کد، نه تنها امنیت پروژه رو به خطر می‌اندازه، بلکه فرآیند تغییر اون‌ها را در محیط‌های مختلف (مثل محیط توسعه و محیط پروداکشن) به یک چالش بزرگ تبدیل می‌کنه.
اینجاست که فایل‌های .env به کار میان. در این مقاله می‌خوایم بررسی کنیم که فریم‌ورک Next.js چطور کار با متغیرهای محیطی رو برای ما راحت کرده، این فایل‌ها چه اولویت‌هایی دارن و چطور می‌تونیم به بهینه‌ترین شکل ممکن از اون‌ها استفاده کنیم.
چطور فایل‌های .env زندگی ما رو راحت‌تر می‌کنن؟
به زبان ساده، متغیرهای محیطی به شما اجازه میدن تنظیمات پروژه رو از خودِ کد جدا کنید. Next.js به صورت پیش‌فرض و بدون نیاز به نصب هیچ پکیج اضافی (مثل dotenv)، از این فایل‌ها پشتیبانی می‌کنه.
شما می‌تونید چندین فایل .env برای سناریوهای مختلف داشته باشید، اما نکته مهم اینه که بدونید Next.js با چه ترتیبی و بر اساس چه اولویتی این فایل‌ها رو می‌خونه.
ترتیب اولویت فایل‌های .env در Next.js (از بیشترین به کمترین):
نکست‌جی‌اس برای جابجایی بین محیط‌های مختلف (توسعه، پروداکشن و تست) بسیار هوشمند عمل می‌کنه. ترتیب خونده شدن فایل‌ها به این صورت هستش:
فایل‌های اختصاصی محیط با پسوند .local: مثل .env.development.local یا .env.production.local. این فایل‌ها بالاترین اولویت رو دارن و معمولاً در سیستم هر برنامه‌نویس به صورت محلی ذخیره می‌شن و نباید به گیت‌هاب push بشن.
فایل .env.local: این فایل در تمامی محیط‌ها (به جز محیط تست) اولویت بسیار بالایی داره و برای تعریف متغیرهای محلی عمومی استفاده میشه.
فایل‌های اختصاصی محیط: شامل .env.development (وقتی دستور next dev رو می‌زنید)، .env.production (وقتی پروژه با next start بالا میاد) و .env.test. نکست‌جی‌اس بر اساس وضعیت پروژه، فقط یکی از این فایل‌ها رو انتخاب می‌کنه و بقیه رو کاملاً نادیده می‌گیره.
فایل پایه .env: پایین‌ترین اولویت رو داره. این فایل به عنوان یک نسخه‌ی پشتیبان (Fallback) عمل می‌کنه؛ یعنی اگر متغیری در فایل‌های بالایی پیدا نشه، نکست‌جی‌اس این فایل رو چک می‌کنه.
دسترسی به متغیرها: مرز بین سرور و کلانیت
به صورت پیش‌فرض، تمام متغیرهایی که در فایل‌های .env تعریف می‌کنید فقط و فقط در سمت سرور (Node.js) قابل دسترسی هستن (مثلاً در API روت‌ها یا Server Components). این یک قابلیت امنیتی هستش تا اطلاعات حساس شما به مرورگر کاربر ارسال نشه.
اما اگر بخواید از یک متغیر در کامپوننت‌های سمت کلایت (Client Components) استفاده کنید، باید این کار رو انجام بدید:
کافیه اسم متغیر رو با عبارت NEXT_PUBLIC_ شروع کنید. با این کار، Next.js متوجه میشه که این متغیر حساس نیست و اجازه میده که در سمت کلایت هم بهش دسترسی داشته باشید:
# فقط در سمت سرور دسترسی دارد
ANALYTICS_SECRET_KEY=secret_123
# هم در سرور و هم در کامپوننت‌های کلایت دسترسی دارد
NEXT_PUBLIC_API_URL=https://api.codoloper.com
صدا زدن مداوم
process.env.NEXT_PUBLIC_API_URL در سراسر پروژه، علاوه بر شلوغ کردن کد، دو مشکل اساسی داره: اول اینکه هیچ پیشنهادی (Auto-complete) از سمت ادیتور دریافت نمی‌کنید و دوم اینکه احتمال غلط املایی بالا میره.برای حل این مشکل مراحل زیر رو انجام بدید:
۱. در ریشه (Root) پروژه یک پوشه به نام
configs ایجاد کنید.۲. داخل اون یک فایل به نام
global.ts بسازید.۳. متغیرهای محیطی رو به صورت جدا در این فایل تعریف و اکسپورت کنید:
export const apiUrl = process.env.NEXT_PUBLIC_API_URL;
export const isDevelopment = process.env.NODE_ENV === "development";
export const isProduction = process.env.NODE_ENV === "production";process.env، خیلی راحت متغیر مورد نظرتون رو ایمپورت می‌کنید:import { apiUrl, isProduction} from "@/configs/global";جمع‌بندی
مدیریت هوشمندانه متغیرهای محیطی در Next.js به ما این امکان رو میده که پروژه‌های امن‌تر و منعطف‌تری بسازیم. با درک درست از اولویت‌بندی فایل‌های
.env و استفاده از قابلیت‌هایی مثل پیشوند NEXT_PUBLIC_ و رویکرد Centralized Config، فرآیند توسعه و دیپلوی پروژه آسونتر میشه.نکته مهمِ اینکه: حتماً مطمئن شید که فایل‌های با پسوند
.local در فایل .gitignore شما قرار دارن تا به اشتباه روی مخازن گیت آپلود نشن!شما در پروژه‌هاتون چطور متغیرها رو مدیریت می‌کنید؟ آیا تا به حال با چالش لود نشدن متغیرها در سمت کلایت مواجه شدید؟ نظرات و تجربیات خودتون رو در بخش کامنت‌ها با ما در میون بذارید!
