0Pricing
Frontend Academy · 课时

Next.js API 路由与中间件

在 api/ 目录中创建无服务器 API 端点，在路由处理程序中处理请求，并运行边缘中间件来完成身份验证和重定向。

Next.js API 路由与中间件 是 CoddyKit 上的免费 Frontend Academy 课时。 这是第 4 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 Frontend Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Frontend Academy 课程共包含 4 节课。

为什么使用应用程序接口路由

Next.js 会为您的应用捆绑一个服务器——您可以在页面旁边编写后端端点，而无需单独的 Node 项目。这非常适合代理、表单提交、webhook 和小型应用程序接口。

页面路由器的应用程序接口路由

pages/api/ 中的文件会导出一个使用 Express 风格的（req, res）的默认函数。

// pages/api/users.ts
import type { NextApiRequest, NextApiResponse } from 'next';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method === 'GET') {
    const users = await db.users.findMany();
    return res.json(users);
  }
  if (req.method === 'POST') {
    const user = await db.users.create({ data: req.body });
    return res.status(201).json(user);
  }
  return res.status(405).end();
}

应用路由器的路由处理程序

应用路由器使用 Web 标准的 Request/Response API。每个 HTTP 方法都是一个具名导出。

// app/api/users/route.ts
import { NextResponse } from 'next/server';

export async function GET() {
  const users = await db.users.findMany();
  return NextResponse.json(users);
}

export async function POST(request: Request) {
  const body = await request.json();
  const user = await db.users.create({ data: body });
  return NextResponse.json(user, { status: 201 });
}

动态应用程序接口路由

动态片段的工作方式相同：app/api/users/[id]/route.ts 会匹配 /api/users/123。

// app/api/users/[id]/route.ts
export async function GET(req: Request, { params }: { params: { id: string }}) {
  const user = await db.users.findUnique({ where: { id: params.id }});
  if (!user) return new Response('Not Found', { status: 404 });
  return Response.json(user);
}

读取 Cookie 和请求头

在应用路由器中，请使用 next/headers 提供的辅助函数（它们属于请求作用域）。

import { cookies, headers } from 'next/headers';

export async function GET() {
  const token = cookies().get('token')?.value;
  const userAgent = headers().get('user-agent');
  // ...
}

流式响应

路由处理程序可以返回流式响应——这适用于 AI 聊天补全或大型文件生成。

export async function GET() {
  const encoder = new TextEncoder();
  const stream = new ReadableStream({
    async start(controller) {
      for (let i = 0; i < 5; i++) {
        controller.enqueue(encoder.encode(`chunk ${i}\n`));
        await new Promise(r => setTimeout(r, 500));
      }
      controller.close();
    }
  });
  return new Response(stream);
}

中间件——在路由之前运行

项目根目录中的 middleware.ts 会在请求到达页面或应用程序接口路由之前运行。您可以使用它执行身份验证检查、重定向、请求头重写和 A/B 测试。

// middleware.ts
import { NextResponse, type NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const token = request.cookies.get('token');
  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url));
  }
  return NextResponse.next();
}

中间件匹配器

使用匹配器配置限制中间件运行的路径。

export const config = {
  matcher: [
    '/dashboard/:path*',
    '/api/:path*',
    '/((?!_next/static|_next/image|favicon.ico).*)'
  ]
};

中间件运行时

中间件默认运行在 Edge Runtime 上——这是一个轻量级的 V8 隔离环境（不是完整的 Node）。可用的 API 有限：不能使用 fs 等 Node 模块，也不能使用原生依赖。

使用中间件实现身份验证

常见做法是：在中间件中验证 JWT；如果令牌缺失或无效，则重定向到登录页；将解码后的用户信息附加到请求头中，供下游路由读取。

import jwt from 'jsonwebtoken';

export function middleware(req: NextRequest) {
  const token = req.cookies.get('token')?.value;
  if (!token) return NextResponse.redirect(new URL('/login', req.url));
  try {
    const decoded = jwt.verify(token, process.env.SECRET!);
    const res = NextResponse.next();
    res.headers.set('x-user-id', String(decoded.sub));
    return res;
  } catch {
    return NextResponse.redirect(new URL('/login', req.url));
  }
}

在中间件中进行速率限制

将中间件与 KV 存储（Upstash、Vercel KV）结合，在执行应用程序接口逻辑之前实施按 IP 限制的速率限制。

何时不应使用应用程序接口路由

对于独立的微服务或共享应用程序接口，请部署真正的后端（Hono、Express、NestJS）。Next.js 应用程序接口路由非常适合代理、webhook 和应用专用端点，但不适合向其他客户端提供公共应用程序接口。

快速检查

Next.js 中间件在哪里运行，最常见的使用场景是什么？

回顾：应用程序接口路由与中间件

页面路由器：使用带有 req/res 的 pages/api。应用路由器：使用带有方法导出的 app/api/.../route.ts（GET/POST 等），并采用 Request/Response。通过 next/headers 读取 Cookie/请求头。使用 ReadableStream 实现流式响应。middleware.ts 在路由之前于 Edge 上运行，可用于身份验证、重定向和请求头处理。匹配器配置可以限制路径。对于公共应用程序接口，请使用真正的后端。

常见问题解答

「Next.js API 路由与中间件」课时是免费的吗？

是的 — 「Next.js API 路由与中间件」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Frontend Academy 课程的其余内容，请升级到 CoddyKit PRO。 Frontend Academy 课程共包含 4 节课。

「Next.js API 路由与中间件」这节课中我会学到什么？

在 api/ 目录中创建无服务器 API 端点，在路由处理程序中处理请求，并运行边缘中间件来完成身份验证和重定向。 你通过在浏览器中直接运行的动手代码来练习 Frontend Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Frontend Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Frontend Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 4 节课，共 4 节。

「Next.js API 路由与中间件」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Frontend Academy 课中编写并运行代码吗？

能。每节 Frontend Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

  1. Pages Router 与 App Router
  2. 服务器组件与客户端组件
  3. SSG、SSR 与 ISR
  4. Next.js API 路由与中间件
← 返回 Frontend Academy