Next.js 是一个强大的 React 框架，不仅支持服务端渲染（SSR）和静态站点生成（SSG），还提供了内置的 API 路由功能，使开发者能够轻松构建全栈应用。

传统的全栈开发通常需要单独搭建后端服务（如 Express、NestJS 或 Django），但 Next.js 的 API 路由允许你在同一个项目中处理前端和后端逻辑，无需额外配置。

本文将深入探讨 Next.js API 路由的核心概念、使用方法、最佳实践，并通过实际示例展示如何构建 RESTful API、处理动态路由、集成数据库，以及优化 API 性能。

1. Next.js API 路由简介

1.1 什么是 API 路由？

Next.js API 路由允许你在 pages/api 目录下创建 Node.js 服务器端 API，这些 API 会自动映射到 /api/* 路径。

例如：

• pages/api/hello.js → /api/hello

• pages/api/users/[id].js → /api/users/1

这些 API 路由运行在 Node.js 环境，可以处理 HTTP 请求（GET、POST、PUT、DELETE 等），并返回 JSON、文本或二进制数据。

1.2 为什么使用 Next.js API 路由？

1. 无服务器架构：API 路由自动部署为 Serverless Functions（Vercel、Netlify 等支持）。

2. 简化全栈开发：无需额外搭建 Express 或 FastAPI 后端。

3. 内置 TypeScript 支持：轻松编写类型安全的 API。

4. 自动路由处理：无需手动配置 express.Router()。

5. 与前端无缝集成：可直接在 React 组件中调用 /api 端点。

2. 创建你的第一个 API 路由

2.1 基本 API 示例

在 pages/api/hello.js 中：

export default function handler(req, res) {res.status(200).json({ message: "Hello, Next.js!" });
}

访问 /api/hello 返回：

{ "message": "Hello, Next.js!" }

2.2 处理不同的 HTTP 方法

export default function handler(req, res) {if (req.method === "GET") {res.json({ message: "GET request received" });} else if (req.method === "POST") {res.json({ message: "POST request received" });} else {res.setHeader("Allow", ["GET", "POST"]);res.status(405).end(`Method ${req.method} Not Allowed`);}
}

3. 动态 API 路由

3.1 捕获动态参数

类似于 Next.js 的动态页面路由，API 也支持动态参数：

// pages/api/users/[id].js
export default function handler(req, res) {const { id } = req.query;res.json({ userId: id });
}

访问 /api/users/123 返回：

{ "userId": "123" }

3.2 多级动态路由

// pages/api/blog/[slug]/comments/[commentId].js
export default function handler(req, res) {const { slug, commentId } = req.query;res.json({ post: slug, comment: commentId });
}

访问 /api/blog/nextjs/comments/456 返回：

{ "post": "nextjs", "comment": "456" }

4. 高级 API 路由技巧

4.1 中间件集成

Next.js API 路由支持中间件，可用于：

• CORS 处理

• 身份验证（JWT、Session）

• 请求日志

• 数据验证（Zod、Yup）

示例（使用 cors 中间件）：

import Cors from "cors";const cors = Cors({methods: ["GET", "POST"],
});function runMiddleware(req, res, fn) {return new Promise((resolve, reject) => {fn(req, res, (result) => {if (result instanceof Error) return reject(result);return resolve(result);});});
}export default async function handler(req, res) {await runMiddleware(req, res, cors);res.json({ message: "CORS-enabled API" });
}

4.2 数据库集成

Next.js API 路由可以连接任何数据库（MongoDB、PostgreSQL、Firebase 等）。

示例（MongoDB）：

import { MongoClient } from "mongodb";const uri = process.env.MONGODB_URI;
const client = new MongoClient(uri);export default async function handler(req, res) {await client.connect();const db = client.db("mydb");const data = await db.collection("users").find().toArray();res.json(data);
}

4.3 TypeScript 支持

import type { NextApiRequest, NextApiResponse } from "next";type User = {id: string;name: string;
};export default function handler(req: NextApiRequest,res: NextApiResponse<User[]>
) {const users: User[] = [{ id: "1", name: "Alice" },{ id: "2", name: "Bob" },];res.status(200).json(users);
}

5. 生产环境最佳实践

5.1 错误处理

export default async function handler(req, res) {try {const data = await fetchData();res.json(data);} catch (error) {res.status(500).json({ error: "Internal Server Error" });}
}

5.2 环境变量

使用 .env.local 存储敏感信息：

MONGODB_URI="mongodb://localhost:27017"
API_KEY="your-secret-key"

在 API 路由中访问：

const apiKey = process.env.API_KEY;

5.3 性能优化

• 缓存响应（res.setHeader('Cache-Control', 's-maxage=60')）

• 使用 SWR 进行客户端数据缓存

• 避免阻塞操作（如大型计算）

6. 真实案例：构建一个 Todo API

// pages/api/todos.js
let todos = [];export default function handler(req, res) {if (req.method === "GET") {res.json(todos);} else if (req.method === "POST") {const { task } = req.body;todos.push({ id: Date.now(), task });res.json(todos);} else if (req.method === "DELETE") {const { id } = req.query;todos = todos.filter((todo) => todo.id !== Number(id));res.json(todos);}
}

7. 结论

Next.js API 路由提供了一种简单高效的方式来构建全栈应用，适用于：

• 小型 API 服务

• Serverless 函数

• 数据库交互

• 身份验证

• 代理第三方 API

通过本文，你应该已经掌握了：
✅ 基础 API 路由创建
✅ 动态路由处理
✅ 中间件集成
✅ 数据库连接
✅ TypeScript 支持
✅ 生产环境优化

如果你正在寻找一个简单、高效的全栈解决方案，Next.js API 路由是一个绝佳选择！