概述

Next.js 的 中间件 (Middleware) 是一种在请求完成之前运行的函数，用于对入站请求进行处理和操作。它可以在路由匹配前执行逻辑，用于身份验证、请求重写、重定向、设置响应头等任务。

---

使用场景

• 身份验证：在用户访问页面前检查登录状态。
• 国际化处理：根据用户的语言偏好设置动态重定向。
• A/B 测试：动态分流用户到不同的页面。
• IP 限制：根据访问者 IP 地址限制访问。

---

中间件基本使用

1. 创建 middleware.ts

中间件文件位于项目根目录（如果有 src 则为 src 下 ）下的 middleware.ts。

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';export function middleware(request: NextRequest) {const { pathname } = request.nextUrl;// 示例：阻止访问 `/admin` 路径if (pathname.startsWith('/admin')) {return NextResponse.redirect(new URL('/login', request.url));}// 默认返回请求return NextResponse.next();
}

rewrite 重写是页面的重写，比如将 /admin 页面重写内容为 /user 页面，而我们的路由还是 /admin。重定向是改写路由，比如将 /admin 重定向到 /user ，那么我们直接访问的就是 /user 。

2. 匹配特定路由

通过 matcher 来指定中间件生效的路径。

export const config = {matcher: ['/admin/:path*', '/api/:path*'], // 匹配 /admin 和 /api 路径
};

---

详细示例

示例 1：基于身份验证的访问控制

假设我们有一个 /admin 页面，只有登录用户可以访问。

中间件代码

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';export function middleware(request: NextRequest) {const { pathname } = request.nextUrl;// 检查用户是否有有效的登录 tokenconst token = request.cookies.get('authToken')?.value;if (!token && pathname.startsWith('/admin')) {// 如果未登录，重定向到登录页面return NextResponse.redirect(new URL('/login', request.url));}// 允许请求通过return NextResponse.next();
}

配置匹配路径

export const config = {matcher: ['/admin/:path*'], // 仅在 /admin 路径及子路径生效
};

---

示例 2：基于语言的动态重定向

根据用户浏览器的语言设置，将用户重定向到对应的语言页面。

中间件代码

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';export function middleware(request: NextRequest) {const { pathname } = request.nextUrl;// 如果路径已经包含语言前缀，则不处理if (pathname.startsWith('/en') || pathname.startsWith('/fr')) {return NextResponse.next();}// 获取用户的首选语言const preferredLanguage = request.headers.get('accept-language')?.split(',')[0] || 'en';// 根据语言重定向if (preferredLanguage.startsWith('fr')) {return NextResponse.redirect(new URL('/fr' + pathname, request.url));}// 默认重定向到英语页面return NextResponse.redirect(new URL('/en' + pathname, request.url));
}

目录结构

pages
├── en
│   └── index.tsx
├── fr
│   └── index.tsx
└── middleware.ts

---

示例 3：阻止指定 IP 地址的访问

我们希望屏蔽某些 IP 地址的用户。

中间件代码

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';const BLOCKED_IPS = ['123.45.67.89', '98.76.54.32'];export function middleware(request: NextRequest) {const clientIP = request.ip || request.headers.get('x-forwarded-for') || 'unknown';if (BLOCKED_IPS.includes(clientIP)) {// 如果 IP 被屏蔽，返回 403 Forbidden 响应return new NextResponse('Access forbidden', { status: 403 });}// 允许其他请求通过return NextResponse.next();
}

配置匹配路径

export const config = {matcher: ['/:path*'], // 对所有路径生效
};

---

示例 4：为某些请求添加自定义头

在 API 请求中注入特定的自定义头信息。

中间件代码

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';export function middleware(request: NextRequest) {const response = NextResponse.next();if (request.nextUrl.pathname.startsWith('/api')) {response.headers.set('X-Custom-Header', 'MyCustomValue');}return response;
}

---