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 路由是一個絕佳選擇！

?