Next.js Middleware 是在請求到達 Next.js 頁面渲染或 API 路由前先行執行的請求攔截函式。透過 Middleware,開發者可以在頁面處理前完成身份驗證、路由重定向 (Redirect)、請求重寫 (Rewrite) 及 Header 標頭修改,是控管網站存取與安全的常用機制。
版本說明:Next.js 16 起,
middleware檔名標示為已棄用(deprecated),改名為proxy(檔案proxy.ts、匯出函式proxy),並預設改用 Node.js runtime,Proxy 檔案也不能再設定runtime。本文範例採 Next.js 15 以前的middleware.ts寫法,NextRequest、NextResponse、matcher的用法相同,升級時改檔名與函式名稱即可,也可以執行官方 codemod:npx @next/codemod@canary middleware-to-proxy .
Next 中的 Middleware 是什麼?
Middleware(Middleware)是一種在請求 (Request) 到達特定路由或 API 之前執行的函式。在 Next.js 中,Middleware 可用於攔截並修改請求,使開發者能夠靈活地進行身份驗證、請求重寫、日誌記錄等。
與傳統 Express.js 或 Koa.js 的 Middleware 不同,Next.js 15.5 以前的 Middleware 預設運行於 Edge Runtime(基於標準 Web APIs),部署到 Vercel 等支援邊緣網路的平台時,會在靠近使用者的節點執行。15.5 起 Middleware 可改用 Node.js runtime(正式支援),Next.js 16 的 Proxy 則預設就是 Node.js runtime。
此外,Express.js 的 Middleware 通常運行於傳統 Node.js 伺服器(Server)內部,支援完整的 Node.js 原生 API 與 req.body 解析,而 Next.js Middleware 則更偏向於請求到達前的輕量化攔截與修改,適合應用於身份驗證、A/B 測試及 SEO 優化等場景。
Middleware 的運行時機與架構流向
Middleware 在請求剛進入 Next.js 應用之前執行,它通常在瀏覽器發送請求後、Next.js 處理路由與頁面渲染前運行,適用情境包含:
- 用戶從瀏覽器地址列輸入網址並按 Enter
- 點擊網頁上的連結以導向其他頁面
- 透過 JavaScript 發送 AJAX / fetch 請求
- 表單提交後觸發的 HTTP 請求 (Form Submit)
請求處理架構流向
[ 瀏覽器 HTTP 請求 ]
│
▼
[ Middleware (攔截/驗證) ]
│
├── (未授權/需跳轉) ──► [ 307 重定向 / Redirect ]
│
▼ (通過/Rewrite)
[ Next.js 應用層 (Pages / App Router / API Routes) ]
Middleware 的基本使用與 TypeScript 範例
1. 建立 middleware.ts
在 Next.js 應用的 src 或根目錄下建立 middleware.ts,建議採用 TypeScript 搭配 NextRequest 與 NextResponse 型別標註:
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
export function middleware(request: NextRequest) {
// 取得 Cookie 中的 Token 進行基本驗證
const token = request.cookies.get('auth_token')?.value;
if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
return NextResponse.redirect(new URL('/login', request.url));
}
return NextResponse.next();
}
2. 設定 Middleware 作用範圍
如果 Middleware 只需要作用於特定路徑,可在 middleware.ts 中匯出 config 物件來設定匹配的路由。
Next.js 提供 matcher 屬性來定義 Middleware 的作用範圍,支援路徑模式匹配。例如:
export const config = {
matcher: [
'/dashboard/:path*',
'/admin/:path*'
]
};
這代表 Middleware 只會作用於 /dashboard/ 和 /admin/ 相關頁面,而不影響其他公開請求。
Middleware 與 API Routes 的差異
要使用 Middleware 前,必須先了解它與 API Routes 的權責分工,兩者的差異如下表:
| 比較項目 | Middleware | API Routes |
|---|---|---|
| 執行環境 | 15.5 以前預設 Edge Runtime;15.5 起可選 Node.js;16 的 Proxy 預設 Node.js | 應用伺服器端 (Node.js / Serverless) |
| 適用場景 | 攔截請求、重寫 URL、權限驗證、Header 調整 | 處理商業邏輯、資料庫存取、檔案上傳 |
| 延遲時間 | 採 Edge Runtime 並部署於邊緣網路時,在靠近使用者的節點執行 | 視伺服器地理位置與效能而定 |
| 影響範圍 | 由 matcher 定義的全域或區域請求 | 僅限特定 API 路徑(如 /api/*) |
舉例來說,假設我們有一個用於管理後台的 /admin 路由:
- Middleware 處理身份驗證:攔截請求並檢查使用者是否持有有效的 JWT,若無則直接重定向至
/login。 - API Routes 處理數據請求:在
/api/admin/users內部連接資料庫(如 PostgreSQL 或 MongoDB)執行查詢並返回 JSON 結果。
這樣的組合能確保應用層級的安全性,同時保持數據存取的靈活與效能。
Middleware 的限制與注意事項
Middleware 會在每個符合 matcher 的請求前執行,使用上需注意以下限制(第 2 點的 Node.js 模組限制只適用於 Edge Runtime):
1. 回傳值必須是 Response,不能回傳一般物件
Next.js 13 起,Middleware 可以直接回傳 Response 或 NextResponse(例如 NextResponse.json()),也可以透過 NextResponse.next()、NextResponse.redirect() 或 NextResponse.rewrite() 傳遞請求。直接回傳一般 JavaScript 物件則不是有效的回應。較複雜的商業邏輯與資料存取,仍建議放在 API Routes 中實作。
/*** 錯誤寫法 (Wrong Example) ***/
export function middleware(req: NextRequest) {
// ❌ 嚴禁直接將物件作為 Response 回傳
return { status: 401, message: 'Unauthorized' };
}
/*** 解法程式碼 (Correct Example) ***/
export function middleware(req: NextRequest) {
if (!req.cookies.has('session')) {
// ✅ 正確使用 NextResponse 回傳標準 Response 狀態
return NextResponse.json({ message: 'Unauthorized' }, { status: 401 });
}
return NextResponse.next();
}
2. Edge Runtime 對 fetch() 的支援與存取邊界
過往常有「Middleware 不支援 fetch()」的誤解。事實上,Edge Runtime 原生完整支援標準 Web API fetch(),開發者可直接在 Middleware 中發送 HTTP 請求(例如向第三方 Token 驗證服務或 Auth0 / Supabase 發送請求)。
但使用 fetch() 時必須注意以下限制:
- 執行時間限制:可執行多久依部署平台而定,遠端 API 若回應過慢,會拖慢每個經過 Middleware 的請求,甚至因逾時而失敗。
- Edge Runtime 不支援 Node.js 原生模組:無法使用 Node.js 獨有的原生模組(如
fs、net、child_process),僅能呼叫符合 Web Standard API 的套件;改用 Node.js runtime 則沒有這項限制。
/*** 在 Middleware 中使用標準 fetch() 驗證 Token ***/
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
export async function middleware(request: NextRequest) {
const token = request.headers.get('Authorization');
if (!token) {
return NextResponse.redirect(new URL('/login', request.url));
}
// ✅ Edge Runtime 原生支援 fetch() API
const authResponse = await fetch('https://api.example.com/v1/verify', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ token }),
});
if (!authResponse.ok) {
return NextResponse.redirect(new URL('/login', request.url));
}
return NextResponse.next();
}
3. req.body 無法直接讀取與存取權限表
在 Middleware 中,無法直接讀取或解析 req.body(或 HTTP POST 的 Payload)。這是因為 HTTP 請求體屬於數據串流(Stream),若在邊緣端提前消耗(Consume)該串流,後續到達 API Route 或頁面時將無法再次讀取 Body。
以下整理 Middleware 中常見請求屬性的存取限制表:
| 屬性 | 可存取 | 可修改 | 說明 |
|---|---|---|---|
req.url | ✅ | ❌ | 獲取請求的完整 URL 字串 |
req.nextUrl | ✅ | ❌ | Next.js 解析後的 URL 物件,適用於 Rewrite 與 Redirect |
req.method | ✅ | ❌ | 獲取 HTTP 請求方法(如 GET、POST) |
req.headers | ✅ | ✅ | 可讀取與透過 NextResponse 設定請求與回應標頭 |
req.cookies | ✅ | ✅ | 可讀取與寫入 Cookie(如 req.cookies.get('token')) |
req.ip | ❌ | ❌ | Next.js 15 已移除,IP 改由部署平台提供(例如 Vercel 的 @vercel/functions 提供 ipAddress) |
req.body | ❌ | ❌ | 無法讀取,強行解析將導致串流鎖定或錯誤,需於 API Routes 處理 |
常見問題(Q&A)
Q1:能在 Next.js Middleware 中連接資料庫(如 ORM / PostgreSQL)嗎?
取決於執行環境。在 Edge Runtime 下,依賴 Node.js 原生 TCP Socket 模組的資料庫驅動(如 pg)無法執行,需改用支援 HTTP / WebSockets 的資料庫 SDK(如 Supabase、Neon)。15.5 起 Middleware 可改用 Node.js runtime(16 的 Proxy 預設即為 Node.js),就能使用一般驅動。不過 Middleware 會在每個符合 matcher 的請求前執行,查資料庫會拖慢這些請求,較重的查詢仍建議移至 API Routes。
Q2:為什麼在 Middleware 設定了 response.headers.set(),後端頁面卻讀取不到?
若要將修改後的 Header 傳遞給後續的頁面或 API 路由,必須將修改寫入 request.headers,並於 NextResponse.next({ request: { headers } }) 中帶入,而非僅修改回傳的 Response Header。
// ✅ 正確帶入修改後的 Request Headers
const requestHeaders = new Headers(request.headers);
requestHeaders.set('x-user-id', '12345');
return NextResponse.next({
request: {
headers: requestHeaders,
},
});
Q3:Middleware 檔案可以放置在哪些目錄?
依官方文件,middleware.ts(或 .js)放在專案根目錄,有使用 src 時則放在 src/ 內,也就是與 app 或 pages 同層。檔案只能匯出一個函式,邏輯較多時可拆成模組再匯入。Next.js 16 起檔名改為 proxy.ts,位置規則相同。
Q4:如何在開發環境確認 Middleware 是否正確執行?
可以在 Middleware 函式內部使用 console.log() 印出日誌。當請求觸發時,訊息會印出於啟動 next dev 的 Terminal 控制台中(而非瀏覽器的 Console)。此外,亦可透過瀏覽器 DevTools 的 Network 分頁檢查 Request / Response Header 變化進行排查。
結論
Middleware 在 Next.js 中提供了請求攔截能力,能把授權檢查、語系切換與路由轉向等邏輯提前到頁面渲染之前處理。只要掌握所用執行環境(Edge Runtime 或 Node.js runtime)的 API 邊界,並避免在 Middleware 中處理串流 Body 或過重的運算,就能減輕後端頁面與 API 的負擔。升級到 Next.js 16 時,記得把 middleware.ts 改名為 proxy.ts。
參考資料與延伸閱讀
- Next.js 官方文件:Proxy(原 Middleware)的概念、用法與版本紀錄
- Next.js 官方 API 參考:NextRequest 物件說明
- Next.js 官方 API 參考:NextResponse 物件說明
- Next.js 官方文件:Edge Runtime 的運行環境與限制
- MDN Web Docs:Fetch API 的 Request 物件規範
- 延伸閱讀:簡單說明 Next 中 middleware.js、_app.js、_document.js、index.js 載入順序與作用
- 延伸閱讀:Next.js 專案初始化與架構設計:由 React CSR 轉移至 SSR 之工程實務規範
發佈留言