伺服器

server/ 目錄用於向你的應用程式註冊 API 和伺服器處理程式。

Nuxt 會自動掃描這些目錄中的檔案，以註冊支援熱模組替換 (HMR) 的 API 和伺服器處理程式。

目錄結構
-| server/
---| api/
-----| hello.ts      # /api/hello
---| routes/
-----| bonjour.ts    # /bonjour
---| middleware/
-----| log.ts        # log all requests

每個檔案都應匯出一個使用 defineEventHandler() 或 eventHandler() (別名) 定義的預設函式。

處理程式可以直接返回 JSON 資料、一個 Promise，或者使用 event.node.res.end() 傳送響應。

server/api/hello.ts
export default defineEventHandler((event) => {
  return {
    hello: 'world',
  }
})

你現在可以在你的頁面和元件中通用地呼叫這個 API

app/pages/index.vue
<script setup lang="ts">
const { data } = await useFetch('/api/hello')
</script>

<template>
  <pre>{{ data }}</pre>
</template>

伺服器路由

~/server/api 目錄中的檔案會自動在其路由中新增 /api 字首。

要新增沒有 /api 字首的伺服器路由，請將它們放入 ~/server/routes 目錄。

示例

server/routes/hello.ts
export default defineEventHandler(() => 'Hello World!')

根據上面的示例，/hello 路由將可以透過以下方式訪問：https://:3000/hello.

請注意，目前伺服器路由不支援像 頁面 那樣完整的動態路由功能。

伺服器中介軟體

Nuxt 會自動讀取 ~/server/middleware 中的任何檔案，為你的專案建立伺服器中介軟體。

中介軟體處理程式將在任何其他伺服器路由之前對每個請求執行，以新增或檢查請求頭、記錄請求或擴充套件事件的請求物件。

中介軟體處理程式不應返回任何內容（也不應關閉或響應請求），而只應檢查或擴充套件請求上下文或丟擲錯誤。

示例

server/middleware/log.ts
export default defineEventHandler((event) => {
  console.log('New request: ' + getRequestURL(event))
})
server/middleware/auth.ts
export default defineEventHandler((event) => {
  event.context.auth = { user: 123 }
})

伺服器外掛

Nuxt 會自動讀取 ~/server/plugins 目錄中的所有檔案，並將它們註冊為 Nitro 外掛。這允許擴充套件 Nitro 的執行時行為並掛接到生命週期事件。

示例

server/plugins/nitroPlugin.ts
export default defineNitroPlugin((nitroApp) => {
  console.log('Nitro plugin', nitroApp)
})
在 Nitro 外掛 中閱讀更多。

伺服器實用程式

伺服器路由由以下提供支援h3js/h3它附帶了一組方便的輔助函式。

在 可用的 H3 請求輔助函式 中閱讀更多。

你可以在 ~/server/utils 目錄中自行新增更多輔助函式。

例如，你可以定義一個自定義處理程式實用程式，它包裝原始處理程式並在返回最終響應之前執行額外操作。

示例

server/utils/handler.ts
import type { EventHandler, EventHandlerRequest } from 'h3'

export const defineWrappedResponseHandler = <T extends EventHandlerRequest, D> (
  handler: EventHandler<T, D>,
): EventHandler<T, D> =>
  defineEventHandler<T>(async (event) => {
    try {
      // do something before the route handler
      const response = await handler(event)
      // do something after the route handler
      return { response }
    } catch (err) {
      // Error handling
      return { err }
    }
  })

伺服器型別

此功能適用於 Nuxt >= 3.5

秘訣

路由引數

伺服器路由可以在檔名中使用方括號內的動態引數，例如 /api/hello/[name].ts，並透過 event.context.params 訪問。

server/api/hello/[name].ts
export default defineEventHandler((event) => {
  const name = getRouterParam(event, 'name')

  return `Hello, ${name}!`
})
或者，可以使用 getValidatedRouterParams 配合 Zod 等模式驗證器，以確保執行時和型別安全。

你現在可以在 /api/hello/nuxt 上通用地呼叫此 API，並獲得 Hello, nuxt!。

匹配 HTTP 方法

處理程式檔名可以以 .get、.post、.put、.delete 等字尾，以匹配請求的HTTP 方法.

server/api/test.get.ts
export default defineEventHandler(() => 'Test get handler')
server/api/test.post.ts
export default defineEventHandler(() => 'Test post handler')

根據上面的示例，使用以下方式獲取 /test

  • GET 方法：返回 Test get handler
  • POST 方法：返回 Test post handler
  • 任何其他方法：返回 405 錯誤

你還可以使用目錄內的 index.[method].ts 來以不同方式組織程式碼，這對於建立 API 名稱空間很有用。

export default defineEventHandler((event) => {
  // handle GET requests for the `api/foo` endpoint
})

捕獲所有路由

捕獲所有路由有助於回退路由處理。

例如，建立名為 ~/server/api/foo/[...].ts 的檔案將為所有不匹配任何路由處理程式的請求（例如 /api/foo/bar/baz）註冊一個捕獲所有路由。

server/api/foo/[...].ts
export default defineEventHandler((event) => {
  // event.context.path to get the route path: '/api/foo/bar/baz'
  // event.context.params._ to get the route segment: 'bar/baz'
  return `Default foo handler`
})

你可以透過使用 ~/server/api/foo/[...slug].ts 為捕獲所有路由設定名稱，並透過 event.context.params.slug 訪問它。

server/api/foo/[...slug].ts
export default defineEventHandler((event) => {
  // event.context.params.slug to get the route segment: 'bar/baz'
  return `Default foo handler`
})

請求體處理

server/api/submit.post.ts
export default defineEventHandler(async (event) => {
  const body = await readBody(event)
  return { body }
})
或者，使用 readValidatedBody 和 Zod 等模式驗證器來確保執行時和型別安全。

你現在可以使用以下方式通用地呼叫此 API：

app/app.vue
<script setup lang="ts">
async function submit () {
  const { body } = await $fetch('/api/submit', {
    method: 'post',
    body: { test: 123 },
  })
}
</script>
我們只在檔名中使用 submit.post.ts 來匹配接受請求體的 POST 方法請求。當在 GET 請求中使用 readBody 時，readBody 將丟擲 405 Method Not Allowed HTTP 錯誤。

查詢引數

查詢示例 /api/query?foo=bar&baz=qux

server/api/query.get.ts
export default defineEventHandler((event) => {
  const query = getQuery(event)

  return { a: query.foo, b: query.baz }
})
或者，使用 getValidatedQuery 配合 Zod 等模式驗證器來確保執行時和型別安全。

錯誤處理

如果沒有丟擲錯誤，將返回狀態碼 200 OK。

任何未捕獲的錯誤將返回 500 Internal Server Error HTTP 錯誤。

要返回其他錯誤程式碼，請使用 createError 丟擲異常。

server/api/validation/[id].ts
export default defineEventHandler((event) => {
  const id = Number.parseInt(event.context.params.id) as number

  if (!Number.isInteger(id)) {
    throw createError({
      statusCode: 400,
      statusMessage: 'ID should be an integer',
    })
  }
  return 'All good'
})

狀態碼

要返回其他狀態碼，請使用 setResponseStatus 實用程式。

例如，要返回 202 Accepted

server/api/validation/[id].ts
export default defineEventHandler((event) => {
  setResponseStatus(event, 202)
})

執行時配置

export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig(event)

  const repo = await $fetch('https://api.github.com/repos/nuxt/nuxt', {
    headers: {
      Authorization: `token ${config.githubToken}`,
    },
  })

  return repo
})
將 event 作為引數傳遞給 useRuntimeConfig 是可選的，但建議傳遞它以獲取執行時配置，該配置在執行時為伺服器路由被 環境變數 覆蓋。

請求 Cookie

server/api/cookies.ts
export default defineEventHandler((event) => {
  const cookies = parseCookies(event)

  return { cookies }
})

轉發上下文和請求頭

預設情況下，在伺服器路由中發起 fetch 請求時，傳入請求的請求頭和請求上下文都不會被轉發。你可以使用 event.$fetch 在伺服器路由中發起 fetch 請求時轉發請求上下文和請求頭。

server/api/forward.ts
export default defineEventHandler((event) => {
  return event.$fetch('/api/forwarded')
})
那些不應被轉發的請求頭將不被包含在請求中。這些請求頭包括，例如：transfer-encoding、connection、keep-alive、upgrade、expect、host、accept

響應後等待 Promise

在處理伺服器請求時，你可能需要執行不應阻塞客戶端響應的非同步任務（例如，快取和日誌記錄）。你可以使用 event.waitUntil 在後臺等待 Promise，而不會延遲響應。

event.waitUntil 方法接受一個 Promise，該 Promise 將在處理程式終止之前被等待，確保即使伺服器在傳送響應後立即終止處理程式，任務也能完成。這與執行時提供程式整合，以利用它們的原生能力在傳送響應後處理非同步操作。

server/api/background-task.ts
const timeConsumingBackgroundTask = async () => {
  await new Promise(resolve => setTimeout(resolve, 1000))
}

export default eventHandler((event) => {
  // schedule a background task without blocking the response
  event.waitUntil(timeConsumingBackgroundTask())

  // immediately send the response to the client
  return 'done'
})

高階用法

Nitro 配置

你可以在 nuxt.config 中使用 nitro 鍵直接設定Nitro 配置.

這是一個高階選項。自定義配置可能會影響生產部署，因為當 Nuxt 的 semver-minor 版本升級 Nitro 時，配置介面可能會隨時間變化。
nuxt.config.ts
export default defineNuxtConfig({
  // https://nitro.build/config
  nitro: {},
})
在 文件 > 4 X > 指南 > 概念 > 伺服器引擎 中閱讀更多。

巢狀路由器

server/api/hello/[...slug].ts
import { createRouter, defineEventHandler, useBase } from 'h3'

const router = createRouter()

router.get('/test', defineEventHandler(() => 'Hello World'))

export default useBase('/api/hello', router.handler)

傳送流

這是一個實驗性功能，可在所有環境中使用。
server/api/foo.get.ts
import fs from 'node:fs'
import { sendStream } from 'h3'

export default defineEventHandler((event) => {
  return sendStream(event, fs.createReadStream('/path/to/file'))
})

傳送重定向

server/api/foo.get.ts
export default defineEventHandler(async (event) => {
  await sendRedirect(event, '/path/redirect/to', 302)
})

傳統處理程式或中介軟體

server/api/legacy.ts
export default fromNodeMiddleware((req, res) => {
  res.end('Legacy handler')
})
可以使用h3js/h3實現傳統支援，但建議儘可能避免使用傳統處理程式。
server/middleware/legacy.ts
export default fromNodeMiddleware((req, res, next) => {
  console.log('Legacy middleware')
  next()
})
切勿將 next() 回撥與 async 或返回 Promise 的傳統中介軟體結合使用。

伺服器儲存

Nitro 提供了一個跨平臺的儲存層。為了配置額外的儲存掛載點，你可以使用 nitro.storage 或 伺服器外掛。

新增 Redis 儲存的示例

使用 nitro.storage

nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    storage: {
      redis: {
        driver: 'redis',
        /* redis connector options */
        port: 6379, // Redis port
        host: '127.0.0.1', // Redis host
        username: '', // needs Redis >= 6
        password: '',
        db: 0, // Defaults to 0
        tls: {}, // tls/ssl
      },
    },
  },
})

然後在你的 API 處理程式中

server/api/storage/test.ts
export default defineEventHandler(async (event) => {
  // List all keys with
  const keys = await useStorage('redis').getKeys()

  // Set a key with
  await useStorage('redis').setItem('foo', 'bar')

  // Remove a key with
  await useStorage('redis').removeItem('foo')

  return {}
})
閱讀更多關於 Nitro 儲存層的資訊。

或者，你可以使用伺服器外掛和執行時配置建立儲存掛載點

import redisDriver from 'unstorage/drivers/redis'

export default defineNitroPlugin(() => {
  const storage = useStorage()

  // Dynamically pass in credentials from runtime configuration, or other sources
  const driver = redisDriver({
    base: 'redis',
    host: useRuntimeConfig().redis.host,
    port: useRuntimeConfig().redis.port,
    /* other redis connector options */
  })

  // Mount driver
  storage.mount('redis', driver)
})