概述

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;

  // 检查用户是否有有效的登录 token
  const 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;
}