proxy.ts در Next.js — محافظ بی‌صدا در لبهٔ اپلیکیشن

۱. چرا proxy.ts؟

فایل middleware.ts در نسخه‌های جدید Next.js به proxy.ts تغییر نام داده تا با Express اشتباه نشود و نقش آن به‌عنوان پروکسی شبکه‌ای در لبهٔ اپلیکیشن واضح‌تر باشد.

۲. قابلیت‌های proxy.ts

عمل	کد
ریدایرکت	NextResponse.redirect()
بازنویسی مسیر	NextResponse.rewrite()
تنظیم هدر	response.headers.set()
تنظیم کوکی	response.cookies.set()
محدودسازی دسترسی	return new Response('401')
ثبت آنالیتیکس	event.waitUntil(fetch(...))

۳. ساختار اولیه فایل proxy.ts

// proxy.ts
import { NextResponse, NextRequest } from 'next/server'

export function proxy(request: NextRequest) {
  return NextResponse.redirect(new URL('/home', request.url))
}

export const config = {
  matcher: '/about/:path*',
}

۴. تعریف matcher دقیق

• مسیر خاص: '/about'
• چند مسیر: ['/dashboard', '/profile']
• Wildcard: '/blog/:path*'
• Regex: '/(?!api|_next/static).*'

۵. مثال‌های واقعی

۵.۱ محافظ احراز هویت

if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
  return NextResponse.redirect(new URL('/login', request.url))
}

۵.۲ تست A/B

url.pathname = random < 0.5 ? '/experiments/a' : '/experiments/b'

۵.۳ ریدایرکت بر اساس کشور

if (country === 'IR') {
  return NextResponse.rewrite(new URL('/fa', request.url))
}

۵.۴ تنظیم CORS برای API

response.headers.set('Access-Control-Allow-Origin', origin)

۵.۵ هدرهای امنیتی

response.headers.set('X-Frame-Options', 'DENY')

۶. وظایف پس‌زمینه با waitUntil

event.waitUntil(fetch('https://analytics.com/log', { method: 'POST', body: ... }))

۷. تست فایل proxy.ts

unstable_doesProxyMatch({ config, url: '/dashboard' })

۸. بهترین شیوه‌ها

انجام بده	انجام نده
matcher دقیق بنویس	روی همه مسیرها اجرا نکن
زود return کن	منطق سنگین اجرا نکن
از waitUntil برای لاگ استفاده کن	پاسخ را بلوکه نکن
کوکی و هدر تنظیم کن	به state جهانی وابسته نباش
کد stateless بنویس	ماژول‌های app را share نکن

۹. مهاجرت از middleware.ts به proxy.ts

npx @next/codemod@canary middleware-to-proxy .

۱۰. چه زمانی از proxy استفاده کنیم؟

کاربرد	استفاده از proxy؟
ریدایرکت احراز هویت	بله
تست A/B	بله
فلگ ویژگی‌ها	بله
ثبت لاگ	بله (با waitUntil)
محدودسازی نرخ	بله (در edge)
ریدایرکت SEO	بله
رندر صفحه	نه — از Server Component یا getServerSideProps استفاده کن