建立 2026-09-16 更新 2026-09-16

Route Handlers（API 路由）

除了頁面，Next.js 也能在同一個專案裡直接寫後端 API：在 app/ 底下的任何資料夾放一個 route.ts，就能處理 HTTP 請求。這讓小型專案不需要另外架一台後端伺服器，前後端可以放在同一個 repo 裡一起開發、一起部署。

基本寫法

import { NextResponse } from "next/server";

export async function GET() {
  return NextResponse.json({ message: "Hello from Next.js!" });
}

造訪 /api/hello 就會拿到這段 JSON 回應。同一層資料夾不能同時有 page.tsx 和 route.ts——一個路徑要嘛是頁面、要嘛是 API，不能兩者都是。

Route Handler 支援的方法對應標準 HTTP 動詞：GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS，每個方法各自是一個具名的 export。

讀取查詢字串與請求內容

import { NextRequest, NextResponse } from "next/server";

export async function GET(request: NextRequest) {
  const query = request.nextUrl.searchParams.get("q");
  const results = await search(query);
  return NextResponse.json(results);
}

export async function POST(request: NextRequest) {
  const body = await request.json();
  const created = await createItem(body);
  return NextResponse.json(created, { status: 201 });
}

NextRequest 是標準 Web Request 的擴充版，額外提供 nextUrl.searchParams 方便讀取查詢字串；NextResponse.json() 則是快速回傳 JSON 並設定正確的 Content-Type。

動態 API 路由

跟頁面的動態路由用法一致，方括號資料夾名稱可以對應到 params：

import { NextRequest, NextResponse } from "next/server";

export async function GET(
  request: NextRequest,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  const post = await getPost(id);

  if (!post) {
    return NextResponse.json({ error: "找不到文章" }, { status: 404 });
  }

  return NextResponse.json(post);
}

什麼時候用 Route Handlers，什麼時候用 Server Actions

Next.js 另外提供 Server Actions（在函式標記 "use server"，可以直接從表單或元件呼叫，不用自己組 fetch），跟 Route Handlers 用途有部分重疊：

• 需要提供給外部系統呼叫的 API（例如手機 App、第三方 Webhook）——用 Route Handlers，因為它是標準 HTTP 端點。
• 只是自家頁面裡的表單送出、按鈕觸發的資料異動——Server Actions 通常更直接，不需要額外定義 API 形狀。

推薦影音

Route Handlers 實作示範

簡述：Codevolution 這支影片示範如何建立 route.ts、處理不同 HTTP 方法與動態參數，可以搭配上面的範例一起練習。

下一步

前後端都寫好之後，最後一步是把應用程式部署上線，詳見 部署上線。