Middleware احراز هویت در Next.js: الگوی تمیز بدون باگ

خلاصه: احراز هویت را در middleware.ts متمرکز کنید؛ با یک تابع isAuthenticated و لیست مسیرهای محافظت‌شده، ریدایرکت و رفرش توکن را تمیز و بدون تکرار در هر صفحه مدیریت کنید.

چرا Middleware برای Auth

چک کردن سشن در هر page.tsx تکراری و خطاپذیر است. middleware.ts قبل از رندر روی Edge اجرا می‌شود، پس می‌تواند درخواست را زود رد یا هدایت کند، cookie را بخواند و حتی توکن را رفرش کند. این یعنی یک جا برای همه قوانین و بدون نشت منطق به کامپوننت.

اگر مرز کلاینت و سرور برایتان مهم است، مرور آلودگی RSC و مرز use-client و کش و PPR در Next.js 15 کمک می‌کند بفهمید چه چیزی باید در middleware بماند و چه چیزی در Server Actions.

اسکلت تمیز middleware.ts

یک فایل middleware.ts در ریشه پروژه بسازید و مسیرها را جدا تعریف کنید:

// middleware.ts
import { NextResponse, NextRequest } from "next/server";

const PUBLIC_PATHS = ["/", "/login", "/blog", "/api/auth"];
const PROTECTED_PREFIXES = ["/dashboard", "/account", "/admin"];

function isPublic(pathname: string) {
  return PUBLIC_PATHS.some((p) => pathname === p || pathname.startsWith(p + "/"));
}

function isProtected(pathname: string) {
  return PROTECTED_PREFIXES.some((p) => pathname.startsWith(p));
}

export function middleware(req: NextRequest) {
  const { pathname } = req.nextUrl;
  const token = req.cookies.get("session")?.value;

  if (isPublic(pathname)) return NextResponse.next();
  if (isProtected(pathname) && !token) {
    const url = req.nextUrl.clone();
    url.pathname = "/login";
    url.searchParams.set("next", pathname);
    return NextResponse.redirect(url);
  }
  return NextResponse.next();
}

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};

نکته: matcher فایل‌های استاتیک را حذف می‌کند تا Edge بیهوده درگیر نشود.

رفرش توکن و کوکی امن

توکن کوتاه‌مدت + رفرش‌توکن امن‌ترین ترکیب است. در middleware فقط اعتبارسنجی سبک انجام دهید؛ رفرش سنگین را به route handler بسپارید:

کوکی را همیشه httpOnly و secure بگذارید و هرگز توکن را در localStorage نگه ندارید. برای بهینه‌سازی تصویر و دارایی‌ها، راهنمای بهینه‌سازی تصویر Next.js را ببینید تا ریدایرکت‌ها با کش تصویر تداخل نکند.

جدول تصمیم ریدایرکت

| وضعیت کاربر | مسیر درخواستی | رفتار Middleware | کد | |---|---|---|---| | مهمان | /dashboard | ریدایرکت به /login?next=/dashboard | 307 | | مهمان | /login | اجازه ورود | 200 | | لاگین‌شده | /login | ریدایرکت به /dashboard | 307 | | لاگین‌شده | /dashboard | اجازه + هدر x-user-id | 200 |

برای لاگین‌شده‌ای که به /login می‌رود، ریدایرکت معکوس تجربه را تمیز می‌کند:

چک‌لیست امنیتی قبل از دیپلوی

• [x] AUTH_SECRET در env ست شده و در گیت نیست
• [x] کوکی httpOnly, secure, sameSite=lax دارد
• [ ] مسیرهای public و protected دقیق لیست شده‌اند
• [ ] ریدایرکت next فقط به مسیر داخلی مجاز است (جلوگیری از open redirect)
• [ ] لاگ خطا بدون نشت توکن

مینی‌کیس: یک پنل سفارش برای فروشگاه تهرانی، قبلا چک لاگین را در هر صفحه کپی کرده بود؛ با انتقال به middleware، ۱۲۰ خط کد تکراری حذف شد، باگ «کاربر لاگین‌شده دوباره به لاگین می‌رود» حل شد و زمان پاسخ Edge حدود ۱۲ میلی‌ثانیه کمتر شد.

FAQ

Q: منطق سنگین را در Middleware بگذاریم؟

نه. middleware روی Edge است و باید سبک بماند؛ فقط چک کوکی و ریدایرکت. اعتبارسنجی سنگین، دیتابیس و رفرش را به Route Handler یا Server Action بسپارید.

Q: چطور open redirect را ببندیم؟

پارامتر next را فقط اگر با / شروع شد و شامل // یا http نبود بپذیرید؛ در غیر این صورت به /dashboard بفرستید. هرگز مقدار خام کاربر را مستقیم در redirect نگذارید.

Q: با next/image تداخل دارد؟

اگر matcher درست باشد نه. الگوی !/_next/static و !/_next/image را حتما در config.matcher بگذارید تا درخواست‌های تصویر از middleware عبور نکنند و کش خراب نشود.

نکته‌ی به‌روزرسانی: در نسخه‌های تازه‌ی Next.js این قرارداد middleware نام‌گذاری شده و به proxy تغییر کرده است. اگر روی نسخه‌ی جدید کار می‌کنی، نام فایل را با نسخه‌ی خودت چک کن؛ منطق matcher و کوکی‌ها عوض نمی‌شود.

منابع

• مرجع قرارداد فایل middleware در مستندات Next.js — مرجع رسمی matcher، کوکی‌ها و محدودیت‌های Edge
• مرجع proxy.js — نام جایگزین middleware — تغییر نام قرارداد در نسخه‌های تازه
• ساخت احراز هویت و مجوز مطمئن با middleware — راهنمای مستقل برای الگوهای احراز هویت
• middleware برای Auth: الگوهایی که واقعاً جواب می‌دهند — اشتباه‌های رایج و حلقه‌های ریدایرکت بی‌پایان
• چطور middleware را برای فایل‌های استاتیک رد کنیم — الگوی matcher برای عبور دادن فایل‌های استاتیک