Next.js Middleware 极简教程

Next.js Middleware 极简进阶教程

1. 核心角色：网站的"安检员"

Middleware 就像是进入你网站大门前的安检员。它在请求（Request）到达你的页面（Page）或 API 之前运行。

• 执行时机 ：请求发出后 → Middleware (这里) → 匹配路由 → 渲染页面。
• 能做什么：检查登录没？重定向到新页？改一下请求头？
• 限制 ：默认运行在 Edge Runtime（极轻量，不能读取文件系统，响应必须极快）。

---

2. 两个配置点 (在哪里写？)

A. 文件位置

必须放在项目根目录（或 src 目录下），文件名固定为：middleware.ts。

注意 ：整个项目只能有这一个中间件文件。

B. 过滤规则 (matcher)

你不需要每个请求都过一遍中间件（比如图片、静态文件）。通过 config 来告诉 Next.js 哪些路径需要被"安检"。

TypeScript

// middleware.ts
export const config = {
  // 匹配所有路径，但排除掉 api、静态文件、图片、favicon 等
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
}

---

3. 三个常用招式 (代码怎么写？)

所有的逻辑都写在导出的 middleware 函数里：

招式一：权限拦截（没登录就去登录页）

这是中间件最经典的使用场景。

TypeScript

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

export function middleware(request: NextRequest) {
  const token = request.cookies.get('token') // 读取 Cookie
  const { pathname } = request.nextUrl

  // 如果访问后台页面但没登录，直接重定向到登录页
  if (pathname.startsWith('/dashboard') && !token) {
    return NextResponse.redirect(new URL('/login', request.url))
  }
  
  return NextResponse.next() // 放行
}

招式二：修改请求头（透传信息）

比如你想在所有的请求头里塞一个 x-user-id，让后面的 API 或页面直接用。

TypeScript

export function middleware(request: NextRequest) {
  const requestHeaders = new Headers(request.headers)
  requestHeaders.set('x-hello-from-middleware', 'hello')

  // 将修改后的 Header 传给下游
  return NextResponse.next({
    request: {
      headers: requestHeaders,
    },
  })
}

招式三：处理跨域 (CORS)

如果你的 Next.js 同时充当后端接口，中间件是处理跨域最统一的地方。

TypeScript

export function middleware() {
  const response = NextResponse.next()
  response.headers.set('Access-Control-Allow-Origin', '*')
  response.headers.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS')
  return response
}

---

4. 避坑指南（进阶必看）

1. 绝对路径 ：在中间件里跳转，必须使用 new URL('/path', request.url)。直接写 /path 会报错。

2. 避免大数据请求：中间件是阻塞式的，如果你在里面等一个很慢的外部 API，用户会觉得网页打不开。

3. Cookie 操作 ：中间件读取 Cookie 很快，但修改 响应的 Cookie 需要通过 NextResponse 对象：

   TypeScript

   const response = NextResponse.next()
   response.cookies.set('theme', 'dark') // 在这里设置
   return response

总结：Middleware 的决策逻辑

• 要权限校验？ 用 Middleware。
• 要根据语言/设备重定向？ 用 Middleware。
• 要修改响应头？ 用 Middleware。
• 要查数据库/拿大量数据？ 不要用 Middleware（去页面组件或 Server Action 里写）。