引言:理解 Next.js 中间件的核心价值
在现代 Web 开发中,中间件(Middleware)扮演着至关重要的角色,它位于客户端请求和最终路由处理之间,提供了一个强大的钩子来处理请求、修改响应、执行认证逻辑或进行性能优化。Next.js 从 12 版本开始引入了 Edge Runtime 和 Middleware 支持,允许开发者在请求到达页面之前拦截和处理它。这不仅仅是简单的路由拦截,更是构建高性能、安全应用的基石。
想象一下:用户访问一个受保护的仪表盘页面。传统方式下,你可能需要在每个页面组件中检查用户状态,导致代码重复和潜在的性能开销。而使用 Next.js 中间件,你可以在路由层统一处理认证,拦截无效请求,甚至重写 URL 以提供个性化内容,而无需触碰前端代码。这大大简化了开发流程,并提升了应用的整体效率。
本文将从基础概念入手,逐步深入到高级技巧,涵盖路由拦截、请求处理、性能优化和安全防护。我们将通过实际代码示例详细说明每个步骤,确保你能轻松上手并应用到项目中。无论你是 Next.js 新手还是资深开发者,这份指南都将帮助你掌握中间件的精髓。
1. Next.js 中间件基础:从概念到配置
1.1 什么是 Next.js 中间件?
Next.js 中间件是一种在服务器端运行的代码,它在请求到达目标路由之前执行。它可以访问请求对象(Request),并决定是否继续处理、重定向、重写或直接返回响应。中间件运行在 Edge Runtime 上,这意味着它在全球边缘网络中执行,提供极低的延迟。
关键特性:
拦截路由
:在页面渲染前检查条件,如用户认证。
修改请求/响应
:添加头部、重写 URL 或设置 Cookie。
轻量高效
:基于 Web API,支持异步操作,但不阻塞主线程。
与传统 Express 中间件不同,Next.js 中间件更注重路由集成,且无需额外服务器配置。
1.2 如何设置中间件?
要使用中间件,首先确保你的 Next.js 版本 >= 12(推荐 13+)。在项目根目录创建
middleware.ts
文件(或
middleware.js
)。
步骤 1:安装和初始化
npx create-next-app@latest my-app
cd my-app
npm install next@latest
步骤 2:创建中间件文件
在
app/
或
src/
目录下创建
middleware.ts
(如果使用 App Router)。文件结构示例:
my-app/
├── app/
│ ├── layout.tsx
│ ├── page.tsx
│ └── middleware.ts # 新建此文件
├── package.json
└── next.config.js
步骤 3:基本中间件代码
让我们从一个简单的例子开始:拦截所有请求,添加自定义头部。
// 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-Custom-Header’, ‘Hello from Middleware’);
// 记录请求路径(用于调试)
console.log(`Request to: ${request.nextUrl.pathname}`);
return response;
}
// 配置:指定哪些路由应用中间件
export const config = {
matcher: [‘/dashboard/:path*’, ‘/api/:path*’], // 匹配 /dashboard 下的所有路径,以及 /api 下的所有路径
};
解释
:
NextResponse.next()
:继续处理请求,允许页面正常渲染。
request
对象:包含 URL、头部、方法等信息。
config.matcher
:使用路径匹配器限制中间件范围,避免全局运行(性能优化)。例如,
/dashboard/:path*
匹配
/dashboard
、
/dashboard/settings
等。
运行
npm run dev
,访问
http://localhost:3000/dashboard
,在浏览器开发者工具的 Network 面板中,你会看到响应头部包含
X-Custom-Header
。
常见错误排查
:
如果中间件不生效,检查文件名是否为
middleware.ts
且位于根目录。
Edge Runtime 不支持 Node.js API(如
fs
),如果需要,使用 Server Actions 或 API Routes。
1.3 中间件的生命周期
中间件执行顺序:
接收请求。
运行 middleware 函数。
根据返回值决定:继续(NextResponse)、重定向(NextResponse.redirect)、重写(NextResponse.rewrite)或直接响应。
如果继续,请求进入路由处理。
这使得中间件成为理想的“守门员”。
2. 路由拦截:掌握重定向与重写技巧
路由拦截是中间件的核心应用,常用于认证、访问控制和 URL 优化。
2.1 基本重定向:强制用户登录
假设你有一个
/dashboard
路由,仅对登录用户开放。使用中间件检查 Cookie 或 Token。
示例:基于 Cookie 的认证拦截
// middleware.ts
import { NextResponse } from ‘next/server’;
import type { NextRequest } from ‘next/server’;
export function middleware(request: NextRequest) {
const token = request.cookies.get(‘authToken’)?.value; // 检查认证 Cookie
// 如果未登录且访问受保护路由,重定向到登录页
if (!token && request.nextUrl.pathname.startsWith(‘/dashboard’)) {
return NextResponse.redirect(new URL(‘/login’, request.url));
}
// 如果已登录但访问登录页,重定向到仪表盘
if (token && request.nextUrl.pathname === ‘/login’) {
return NextResponse.redirect(new URL(‘/dashboard’, request.url));
}
return NextResponse.next();
}
export const config = {
matcher: [‘/dashboard/:path*’, ‘/login’],
};
详细说明
:
request.cookies.get(‘authToken’)
:访问请求 Cookie。你可以使用
js-cookie
或其他库在客户端设置 Cookie。
NextResponse.redirect(new URL(‘/login’, request.url))
:创建重定向响应。
request.url
确保重定向使用当前域名。
实际场景
:在登录页面,用户提交表单后,服务器设置 Cookie,然后中间件自动拦截后续请求。测试时,用 Postman 或浏览器手动设置 Cookie:
document.cookie = “authToken=abc123″
。
高级变体:基于 JWT 的检查
如果你使用 JWT,可以在中间件中验证 Token(但注意 Edge Runtime 不支持大型库,如
jsonwebtoken
,推荐使用
jose
)。
import { jwtVerify } from ‘jose’; // npm install jose
export async function middleware(request: NextRequest) {
const token = request.cookies.get(‘authToken’)?.value;
if (!token) return NextResponse.redirect(new URL(‘/login’, request.url));
try {
const { payload } = await jwtVerify(token, new TextEncoder().encode(process.env.JWT_SECRET));
// Token 有效,继续
return NextResponse.next();
} catch {
// Token 无效,重定向并清除 Cookie
const response = NextResponse.redirect(new URL(‘/login’, request.url));
response.cookies.delete(‘authToken’);
return response;
}
}
2.2 URL 重写:隐藏敏感路径或优化 SEO
重写允许内部路由变更,而不改变浏览器 URL。例如,将
/en/products
重写为
/products?lang=en
,实现多语言支持。
示例:多语言路由重写
// middleware.ts
import { NextResponse } from ‘next/server’;
import type { NextRequest } from ‘next/server’;
export function middleware(request: NextRequest) {
const { pathname } = request.nextUrl;
// 检测语言前缀
if (pathname.startsWith(‘/en/’)) {
const newPath = pathname.replace(‘/en/’, ‘/’); // 移除前缀
request.nextUrl.pathname = newPath;
request.nextUrl.searchParams.set(‘lang’, ‘en’); // 添加查询参数
return NextResponse.rewrite(request.nextUrl); // 重写而非重定向
}
if (pathname.startsWith(‘/zh/’)) {
const newPath = pathname.replace(‘/zh/’, ‘/’);
request.nextUrl.pathname = newPath;
request.nextUrl.searchParams.set(‘lang’, ‘zh’);
return NextResponse.rewrite(request.nextUrl);
}
return NextResponse.next();
}
export const config = {
matcher: [‘/en/:path*’, ‘/zh/:path*’],
};
解释
:
NextResponse.rewrite(url)
:内部处理新 URL,但浏览器仍显示原路径。这对 SEO 友好,因为搜索引擎看到的是
/en/products
。
实际应用
:结合 Next.js 的
next-i18next
库,用户访问
/en/products
时,实际渲染
/products
并应用英文翻译。测试:访问
/en/about
,页面内容为
/about
,但 URL 不变。
性能提示
:重写避免了额外的 HTTP 跳转,减少了延迟。在高流量场景下,这能显著提升用户体验。
3. 请求处理:修改头部、处理 API 和优化数据流
中间件可以精细控制请求和响应,包括添加头部、代理 API 或预处理数据。
3.1 添加安全头部
保护应用免受常见攻击,如 XSS 或点击劫持。
示例:添加安全头部
// 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-Frame-Options’, ‘DENY’); // 防止 iframe 嵌入
response.headers.set(‘X-Content-Type-Options’, ‘nosniff’); // 防止 MIME 类型嗅探
response.headers.set(‘Referrer-Policy’, ‘strict-origin-when-cross-origin’); // 控制 referrer
response.headers.set(‘Permissions-Policy’, ‘geolocation=(), microphone=()’); // 限制权限
// CORS 处理(对于 API 路由)
if (request.nextUrl.pathname.startsWith(‘/api/’)) {
response.headers.set(‘Access-Control-Allow-Origin’, ‘*’); // 或指定域名
response.headers.set(‘Access-Control-Allow-Methods’, ‘GET, POST, PUT, DELETE’);
}
return response;
}
export const config = {
matcher: [‘/((?!_next/static|_next/image|favicon.ico).*)’], // 排除静态资源,全局应用
};
详细说明
:
这些头部在所有响应中自动添加,无需在每个 API 或页面中重复。
实际场景
:在生产环境中,结合
helmet
库的替代方案,但中间件更高效,因为它在边缘运行。
测试:使用 curl
curl -I http://localhost:3000
检查头部。
3.2 处理 API 请求:代理和缓存
中间件可以拦截 API 调用,添加认证或缓存逻辑。
示例:API 请求代理与缓存控制
// middleware.ts
import { NextResponse } from ‘next/server’;
import type { NextRequest } from ‘next/server’;
export async function middleware(request: NextRequest) {
if (request.nextUrl.pathname.startsWith(‘/api/proxy’)) {
// 提取原始路径
const targetPath = request.nextUrl.searchParams.get(‘path’) || ‘/’;
const apiUrl = `https://external-api.com${targetPath}`;
// 转发请求(使用 fetch)
const apiResponse = await fetch(apiUrl, {
method: request.method,
headers: { …Object.fromEntries(request.headers), ‘Authorization’: `Bearer ${process.env.API_KEY}` },
body: request.body,
});
// 修改响应:添加缓存头部
const response = new NextResponse(apiResponse.body, {
status: apiResponse.status,
statusText: apiResponse.statusText,
});
// 缓存控制:公共缓存 1 小时
response.headers.set(‘Cache-Control’, ‘public, max-age=3600, s-maxage=3600’);
response.headers.set(‘Vary’, ‘Accept-Encoding’);
return response;
}
return NextResponse.next();
}
export const config = {
matcher: [‘/api/proxy/:path*’],
};
解释
:
使用
fetch
转发请求,添加 API 密钥(安全地从环境变量读取)。
Cache-Control
头部启用 CDN 缓存,减少对外部 API 的调用。
实际场景
:如果你的前端直接调用外部 API,可能暴露密钥。通过中间件代理,密钥保持在服务器端。测试:
fetch(‘/api/proxy?path=/users’)
会返回外部 API 数据,并带有缓存头部。
性能优化
:对于高频 API,结合 Next.js 的
unstable_cache
或此缓存策略,能将响应时间从 200ms 降到 50ms。
4. 性能优化:使用中间件提升应用效率
中间件不是性能杀手,而是优化利器。通过减少不必要的渲染和智能路由,你能显著提升 Core Web Vitals。
4.1 A/B 测试与个性化路由
拦截请求,根据用户属性重写路由,实现动态内容。
示例:基于用户代理的 A/B 测试
// middleware.ts
import { NextResponse } from ‘next/server’;
import type { NextRequest } from ‘next/server’;
export function middleware(request: NextRequest) {
const userAgent = request.headers.get(‘user-agent’) || ”;
const isMobile = /mobile/i.test(userAgent);
if (request.nextUrl.pathname === ‘/’) {
// 移动用户重写到 /mobile-home
if (isMobile) {
return NextResponse.rewrite(new URL(‘/mobile-home’, request.url));
}
// 桌面用户保持原样,但添加 Cookie 标记
const response = NextResponse.next();
response.cookies.set(‘ab-test’, ‘desktop’, { maxAge: 60 * 60 * 24 });
return response;
}
return NextResponse.next();
}
export const config = {
matcher: [‘/’],
};
详细说明
:
检测设备类型,重写到不同页面,实现无缝 A/B 测试。
性能收益
:避免在页面组件中使用
useEffect
检测设备,减少客户端计算。测试:用 Chrome DevTools 模拟移动设备,访问首页应看到
/mobile-home
内容。
4.2 减少 bundle 大小:条件加载
中间件可以设置 Cookie,指导客户端加载不同资源。
实际应用
:为慢速网络用户加载轻量 bundle。通过
request.headers.get(‘save-data’)
检测数据节省模式,重写到低分辨率版本。
优化提示
:结合 Next.js 的动态导入(
dynamic
),中间件确保只在必要时加载组件,减少初始 bundle 20-30%。
5. 安全防护:构建坚固的防御层
安全是中间件的强项。它可以集中处理威胁,而非分散在各处。
5.1 Rate Limiting:防止 DDoS 和暴力破解
使用
upstash/ratelimit
(边缘兼容)实现限流。
示例:API 路由限流
// middleware.ts
import { NextResponse } from ‘next/server’;
import type { NextRequest } from ‘next/server’;
import { Ratelimit } from ‘@upstash/ratelimit’; // npm install @upstash/ratelimit
import { Redis } from ‘@upstash/redis’; // npm install @upstash/redis
const ratelimit = new Ratelimit({
redis: Redis.fromEnv(), // 使用环境变量配置 Redis
limiter: Ratelimit.slidingWindow(10, ‘1 m’), // 每分钟 10 次请求
analytics: true, // 启用分析
});
export async function middleware(request: NextRequest) {
if (request.nextUrl.pathname.startsWith(‘/api/’)) {
const ip = request.ip || ‘127.0.0.1’; // 获取 IP(在 Vercel 中自动)
const { success, limit, reset, remaining } = await ratelimit.limit(ip);
if (!success) {
return new NextResponse(‘Rate limit exceeded’, {
status: 429,
headers: {
‘X-RateLimit-Limit’: limit.toString(),
‘X-RateLimit-Remaining’: remaining.toString(),
‘X-RateLimit-Reset’: reset.toString(),
},
});
}
}
return NextResponse.next();
}
export const config = {
matcher: [‘/api/:path*’],
};
解释
:
Ratelimit.slidingWindow
:滑动窗口算法,精确限流。
安全收益
:防止 API 滥用。在生产中,使用 Vercel KV 或 Upstash 作为后端存储。测试:快速连续调用 API,第 11 次返回 429。
5.2 输入验证与 XSS 防护
中间件可以扫描请求体或查询参数。
示例:基本输入清理
// middleware.ts
import { NextResponse } from ‘next/server’;
import type { NextRequest } from ‘next/server’;
export function middleware(request: NextRequest) {
if (request.method === ‘POST’ && request.nextUrl.pathname.startsWith(‘/api/submit’)) {
// 假设 body 是 JSON
// 注意:Edge Runtime 中,request.body 可能需用 request.json() 读取
const sanitizedUrl = new URL(request.url);
const query = sanitizedUrl.searchParams;
// 简单清理:移除潜在脚本标签
for (const [key, value] of query.entries()) {
if (value.includes(‘