伺服器路由

Nuxt 不僅僅是前端框架，它內建了強大的伺服器引擎 (Nitro)。你可以在 server/ 目錄下直接撰寫後端 API，無需額外架設 Express 或 Koa 伺服器。

Nitro 引擎

Nuxt 的後端由 Nitro 驅動。它是一個極速、輕量且可移植的伺服器引擎。

Nitro Architecture

Browser

Mobile App

Nitro Server Engine

Universal Router

/api/*

HMR

Storage

Assets

Node.jsVercelNetlifyCloudflare WorkersDocker

建立 API

在 server/api/ 目錄下的檔案會自動映射為 API 端點。使用 defineEventHandler 來定義處理邏輯。

File Structure

server/
- api/
  - hello.ts-> /api/hello
  - users/
    - [id].ts-> /api/users/:id

server/api/hello.ts

export default defineEventHandler((event) => {
  return {
    message: 'Hello Nitro!',
    timestamp: new Date()
  }
})

API 實驗室

我們已經在後端建立了一個 /api/demo 端點。試著發送 GET 或 POST 請求，觀察伺服器的回應。

Request Body (JSON)

No body for GET requests

Response

Ready to send request...

HTTP 方法 (Methods)

Nuxt 允許你透過檔案後綴來限制 API 支援的 HTTP 方法，這讓路由定義更語意化。

檔案命名規則

users.get.tsGET ONLY
users.post.tsPOST ONLY
users.put.tsPUT ONLY

範例程式碼

server/api/auth.post.ts

// server/api/auth.post.ts
export default defineEventHandler(async (event) => {
  // 這個處理函式只會回應 POST 請求
  const body = await readBody(event)
  return { status: 'logged_in' }
})

請求處理工具

Nuxt (透過 H3) 提供了一系列工具函式來處理請求內容。這些函式可以直接從 h3 自動引入。

readBody(event)POST/PUT

讀取請求主體 (JSON)。

getQuery(event)GET

讀取 URL 查詢參數 (e.g., ?page=1)。

getRouterParam(event, 'id')Dynamic

讀取動態路由參數 (e.g., /users/123)。

setCookie(event, name, val)Cookie

設定 HTTP Cookie。

server/api/submit.post.ts

export default defineEventHandler(async (event) => {
  // 1. 讀取 Body
  const body = await readBody(event)
  
  // 2. 讀取 Query
  const { type } = getQuery(event)
  
  // 3. 處理邏輯...
  
  return { success: true }
})

錯誤處理

在伺服器端，我們應該使用 createError 來拋出異常。 Nuxt 會自動將這些錯誤轉換為標準的 JSON 回應，並設定正確的 HTTP 狀態碼。

server/api/user/[id].ts

export default defineEventHandler((event) => {
  const id = getRouterParam(event, 'id')

  if (!id) {
    throw createError({
      statusCode: 400,
      statusMessage: 'ID is required',
      data: {
        code: 'MISSING_PARAM',
        details: 'The user ID parameter is missing from the URL.'
      }
    })
  }

  return { id }
})

為什麼不用 throw new Error()?

普通的 throw new Error(...) 預設會回傳 500 Internal Server Error，並且不會包含詳細的錯誤資訊給客戶端。使用 createError 可以精確控制回傳給前端的狀態碼與訊息，這對於 API 開發至關重要。

型別安全

這是 Nuxt 最強大的功能之一。當你在 Vue 頁面中使用 useFetch 呼叫內部 API 時， Nuxt 會自動推斷回傳值的型別，無需手動定義介面。

Server

// server/api/user.ts
export default defineEventHandler(() => {
  return { 
    name: 'Zayn', 
    role: 'admin' 
  }
})

Client

// app.vue
const { data } = await useFetch('/api/user')

// TypeScript 自動知道 data.value 是:
// { name: string; role: string; }
console.log(data.value?.name)