تله params ناهمگام در Next.js 15: چرا ۵۰٪ پروژه‌ها با یک await می‌شکنند

خلاصه: در Next.js 15 params و searchParams دیگر آبجکت ساده نیستند — Promise هستند. اگر await نکنی، در بیلد می‌شکند یا در رانتایم مقدار کهنه می‌گیری. این تله در ۵۰٪ مهاجرت‌ها دیده می‌شود و با یک الگوی ۳ خطی حل می‌شود.

چرا ناهمگام شد؟

تا Next.js 14 این کد کار می‌کرد:

در Next.js 15 همان کد در بیلد اخطار می‌دهد و در رانتایم params.slug برابر undefined می‌شود. دلیل: تیم Next.js برای Partial Prerendering و کش دقیق‌تر params را Promise کرد تا رندر استاتیک و داینامیک از هم جدا شوند — تصمیم درست برای پرفورمنس، ولی بریکینگ برای همه.

اگر پروژه‌ات هنوز روی مهاجرت Tailwind v4 یا بهینه‌سازی تصویر گیر است، این تله را اول فیکس کن؛ بقیه بعداً.

اشتباه رایج vs درست

❌ اشتباه ۱: بدون await

✅ درست: await در سرور کامپوننت

❌ اشتباه ۲: generateMetadata بدون await

❌ اشتباه ۳: searchParams در کلاینت

چک‌لیست مهاجرت ۳۰ ثانیه‌ای

الگوی نهایی برای هر فایل page.tsx / layout.tsx:

کی await لازم نیست؟

• کلاینت کامپوننت با useParams(): هوک useParams() از next/navigation مقدار آماده می‌دهد — نیازی به await نیست. این تله فقط برای props سرور است.
• generateStaticParams: خودش params را می‌سازد و برمی‌گرداند — ورودی ندارد.

FAQ

آیا باید همه پروژه را async کنم؟ فقط فایل‌هایی که params/searchParams می‌گیرند. بقیه می‌توانند sync بمانند. ولی هر Page/Layout که این props را دارد باید async شود.

چرا TypeScript خطا نمی‌دهد؟ اگر params را any تایپ کرده باشی، خطا مخفی می‌ماند. Promise<{ slug: string }> را دقیق تایپ کن تا در tsc بفهمی.

این با اعتبارسنجی فرم Zod تداخل دارد؟ نه — Zod در Server Action جداست. فقط اگر params را در همان Action بخوانی، آنجا هم await لازم است.

جمع‌بندی

Next.js 15 یک await به هر params اضافه کرد تا کش و PPR درست کار کند. اگر بعد از آپدیت صفحه سفید یا مقدار undefined دیدی، اول همین فایل را چک کن. یک await، کل سایت را نجات می‌دهد.