مسئله Environment Poisoning

بیایید این متن را بخش به بخش و دقیق بشکافیم:

۱. صورت مسئله: خطر اشتراک کد بین سرور و کلاینت

در Next.js، شما معمولاً فایل‌هایی دارید که شامل توابع کمکی هستند (مثلاً فایلی به نام lib/data.ts برای دریافت داده‌ها).

مشکل اینجاست که در جاوااسکریپت، هم کامپوننت‌های سمت سرور (Server Components) و هم کامپوننت‌های کلاینت (Client Components) می‌توانند این فایل را import کنند.

اگر تابعی درون این فایل باشد که از یک متغیر محیطیِ محرمانه (مثل process.env.API_KEY) استفاده کند و شما به اشتباه آن تابع را درون یک کامپوننت کلاینت (که کد آن به مرورگر کاربر می‌رود) ایمپورت کنید، خطر لو رفتن آن کلید (API Key) وجود دارد.

۲. مکانیزم دفاعی پیش‌فرض Next.js (جلوگیری از لو رفتن)

Next.js برای جلوگیری از این فاجعه امنیتی یک قانون سخت‌گیرانه دارد:

• فقط متغیرهای محیطی که پیشوند NEXT_PUBLIC_ دارند اجازه دارند به مرورگر (Client bundle) ارسال شوند.

• اگر متغیری این پیشوند را نداشته باشد (مثل همان API_KEY در مثال)، Next.js به جای لو دادن آن، مقدار آن را با یک رشته خالی (Empty String "") جایگزین می‌کند.

نتیجه این مکانیزم: کلید شما لو نمی‌رود (امنیت حفظ می‌شود)، اما اگر آن تابع در کلاینت اجرا شود، به درستی کار نخواهد کرد (چون کلید API خالی است و درخواست شما با خطا مواجه می‌شود). پیدا کردن دلیل این باگ برای برنامه‌نویس می‌تواند بسیار گیج‌کننده باشد.

۳. راه‌حل اصولی: استفاده از پکیج server-only

برای جلوگیری از این خطاهای گیج‌کننده و اطمینان از اینکه کدهای مخصوص سرور هرگز در کلاینت استفاده نمی‌شوند، Next.js راه‌حلی به نام server-only معرفی کرده است.

شما عبارت import 'server-only' را در بالاترین خط فایل lib/data.js قرار می‌دهید.

اتفاقی که می‌افتد: از این به بعد، اگر یک برنامه‌نویس به اشتباه تلاش کند این فایل را در یک Client Component (فایلی که 'use client' دارد) ایمپورت کند، Next.js برنامه را در همان مرحله Build (ساخت) متوقف می‌کند و یک ارور کاملاً واضح می‌دهد. این یعنی جلوگیری از خطا قبل از وقوع آن.

۴. روی دیگر سکه: پکیج client-only

همان‌طور که کدهای سرور نباید در کلاینت اجرا شوند، برخی کدها هم فقط مخصوص مرورگر هستند (مثلاً کدهایی که از شیء window یا localStorage استفاده می‌کنند). اگر این کدها در سرور اجرا شوند، ارور می‌دهند.

برای این موارد، می‌توانید از import 'client-only' در فایل‌های جاوااسکریپتی خود استفاده کنید تا اگر کسی به اشتباه آن‌ها را در Server Component ایمپورت کرد، در زمان Build ارور دریافت کند.

۵. نکات فنی درباره نصب این پکیج‌ها

• نصب این پکیج‌ها از طریق npm/yarn/pnpm (مثلاً pnpm add server-only) از نظر فنی اختیاری است. خود Next.js به صورت داخلی وقتی عبارت import 'server-only' را می‌بیند، منطق ارور دادن را اجرا می‌کند.

• پس چرا نصبشان کنیم؟ نصب آن‌ها فقط برای این است که ابزارهای بررسی کد (مثل ESLint یا TypeScript) خطای “پیدا نشدن پکیج” ندهند. محتوای واقعی این پکیج‌ها روی NPM عملاً خالی است و کار اصلی را خود موتور Next.js انجام می‌دهد.

خلاصه کل متن: برای جلوگیری از اجرای اشتباهِ کدهای سرور (که حاوی اطلاعات حساس هستند) در مرورگر، بالای فایل‌های حساس بنویسید import 'server-only'. این کار باعث می‌شود اگر اشتباهی رخ داد، برنامه بلافاصله با ارور واضح متوقف شود، نه اینکه در سکوت خراب شود.