Next.js Middleware 完整教學：Edge Runtime、認證保護與路由重寫實戰指南

當使用者輸入網址按下 Enter 之後、頁面顯示出來之前，中間可以做多少事情？驗證身份、語言重導、A/B 測試……這些都是 Next.js Middleware 的拿手好戲。

Middleware 是什麼

Middleware 是一段在每個請求到達頁面之前執行的程式碼，跑在 Edge Runtime 上，延遲極低。

執行流程與 Edge Runtime

建立 middleware.ts

import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  const response = NextResponse.next()
  response.headers.set('x-middleware-time', Date.now().toString())
  return response
}

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

如果你學過 Next.js App Router 遷移教學，Middleware 跟 App Router 很搭。

實戰：認證保護

export function middleware(request: NextRequest) {
  const token = request.cookies.get('auth-token')?.value
  if (request.nextUrl.pathname.startsWith('/dashboard') && !token) {
    const loginUrl = new URL('/login', request.url)
    loginUrl.searchParams.set('redirect', request.nextUrl.pathname)
    return NextResponse.redirect(loginUrl)
  }
  return NextResponse.next()
}

URL 重寫與 A/B 測試

if (request.nextUrl.pathname === '/') {
  const bucket = request.cookies.get('ab-bucket')?.value || (Math.random() > 0.5 ? 'a' : 'b')
  const response = bucket === 'b' ? NextResponse.rewrite(new URL('/home-v2', request.url)) : NextResponse.next()
  if (!request.cookies.get('ab-bucket')) response.cookies.set('ab-bucket', bucket, { maxAge: 604800 })
  return response
}

Matcher 設定

export const config = { matcher: ['/dashboard/:path*'] }

Middleware → Proxy 更名

Next.js 2026 年 3 月正式將 middleware 更名為 proxy。把 middleware.ts 改名為 proxy.ts 即可。如果學過 Server Actions，會發現 Next.js 架構越來越清晰。

最佳實踐

• 保持輕量，不做重計算
• 善用 matcher
• 注意 Edge Runtime 限制
• cookie 4KB 限制
• 加上 try/catch

結語

搭配 React Server Components 和 TanStack Query，可以打造既快速又安全的現代 Web 應用。