LightNode Logo

Next.js Middleware 入门指南

Wayne
作者 Wayne ·

Next.js 因将 React 的优势与构建现代 Web 应用的强大能力相结合而闻名。Middleware（中间件）就是其中一项强大的能力。如果你想在请求完成之前执行一些代码（例如验证登录状态或对用户进行重定向），Middleware 就是为这种场景而生的。

什么是 Middleware？

简单来说，Middleware 是在请求到达你的页面或 API 路由之前运行的代码。 它允许你检查传入的请求，并决定下一步该做什么。

例如，你可以：

  • 重定向未登录用户
  • 重写 URL 以提供不同内容
  • 为请求或响应添加自定义 Header
  • 记录请求日志用于分析

👉 可以把 Middleware 想象成用户请求与应用之间的“看门人”。

Middleware 在哪里运行？

  • Middleware 运行在 Edge Runtime 上，距离用户更近、速度更快。
  • 这意味着它不在 Node.js 中运行（无法使用如 fs 之类的 Node API）。
  • 非常适合用于鉴权、重定向、个性化等场景。

如何创建 Middleware

在 Next.js 中，你只需在项目根目录创建一个名为 middleware.js（或 middleware.ts）的文件即可。

示例：简单的请求日志

// middleware.js
import { NextResponse } from "next/server";

export function middleware(request) {
  console.log("Middleware running for:", request.url);
  return NextResponse.next(); // allow request to continue
}

它的执行流程如下：

  • 收到请求。
  • 中间件运行。
  • 如果返回 NextResponse.next()，请求会按正常流程继续处理。

使用 Middleware 实现重定向

你可以很容易地实现重定向。例如，将未登录用户重定向到 /login：

// middleware.js
import { NextResponse } from "next/server";

export function middleware(request) {
  const isLoggedIn = false; // Example check (replace with real logic)

  if (!isLoggedIn) {
    return NextResponse.redirect(new URL("/login", request.url));
  }

  return NextResponse.next();
}

使用 Middleware 实现重写（rewrite）

相较于重定向，你也可以对请求进行“重写”，让用户在 URL 保持不变的情况下看到不同的页面：

// middleware.js
import { NextResponse } from "next/server";

export function middleware(request) {
  const url = request.nextUrl;

  if (url.pathname === "/old-page") {
    return NextResponse.rewrite(new URL("/new-page", request.url));
  }

  return NextResponse.next();
}

👉 这对于处理历史路由或进行 A/B 测试非常有用。

匹配路由（Matcher）

默认情况下，Middleware 会对每一个请求运行。 你可以通过 matcher 配置来进行精确匹配与控制：

// middleware.js
export const config = {
  matcher: ["/dashboard/:path*", "/profile/:path*"],
};

这样一来，Middleware 只会在访问 /dashboard/* 与 /profile/* 时运行。

关键要点

  • Middleware 在请求到达页面或 API 路由之前运行。
  • 运行于 Edge Runtime（无法使用 Node.js API）。
  • 常见用途：
    • 鉴权与授权
    • 重定向与重写
    • 日志与数据分析
    • 本地化（例如基于国家/地区进行重定向）
  • 使用 NextResponse.next() 继续请求；使用 NextResponse.redirect() 进行重定向；使用 NextResponse.rewrite() 改写目标地址。
返回列表