从0死磕全栈之Next.js 中间件（Middleware）详解与实战

Next.js 的 中间件（Middleware） 是一个强大的功能，允许你在请求到达页面或 API 路由之前，在服务器端执行自定义逻辑。它非常适合用于实现身份验证、日志记录、A/B 测试、重定向、国际化等场景。

---

一、什么是 Next.js 中间件？

中间件是一个运行在 Edge Runtime（默认） 或 Node.js Runtime（v15.5+ 支持） 的函数，它在 路由渲染之前 执行。你可以：

• 修改请求头或响应头
• 重写（rewrite）URL
• 重定向（redirect）用户
• 直接返回响应（如 JSON 错误）
• 读取或设置 Cookie
• 实现 CORS、鉴权等逻辑

⚠️ 注意：中间件应尽量轻量，避免依赖共享模块或全局变量。因为中间件可能部署在 CDN 边缘节点上，用于快速处理重定向/重写。

---

二、如何创建中间件？

在项目根目录（或 src 目录下）创建 middleware.ts（或 .js）文件，与 app 或 pages 同级：

/my-next-app
├── src/
│   ├── middleware.ts   ← 中间件文件
│   ├── app/
│   └── ...
└── ...

基本结构

import { NextRequest, NextResponse } from 'next/server'export function middleware(request: NextRequest) {// 中间件逻辑return NextResponse.next() // 继续执行后续流程
}// 可选：配置中间件生效的路径
export const config = {matcher: '/about/:path*',
}

✅ 中间件函数可以是 default 导出，也可以命名为 middleware，但一个文件只能导出一个中间件函数。

---

三、核心功能详解

1. matcher 配置（路径匹配）

通过 config.matcher 控制中间件在哪些路径下运行：

export const config = {matcher: ['/dashboard/:path*',        // 匹配 /dashboard 及其子路径'/api/user/:id',            // 匹配带参数的路径'/((?!api|_next|favicon).*)' // 负向匹配：排除 api、静态资源等]
}

• 支持通配符：*（零或多个）、?（零或一个）、+（一个或多个）
• 支持正则表达式：/((?!api).*)
• 支持高级条件匹配（has / missing）：

export const config = {matcher: [{source: '/api/*',has: