server

server/ 目录用于为您的应用注册 API 和服务端处理器。

Nuxt 会自动扫描这些目录中的文件，以注册 API 和服务端处理器，并支持热模块替换（HMR）。

目录结构

-| server/
---| api/
-----| hello.ts      # /api/hello
---| routes/
-----| bonjour.ts    # /bonjour
---| middleware/
-----| log.ts        # 记录所有请求

每个文件应导出一个使用 defineEventHandler() 或其别名 eventHandler() 定义的默认函数。

处理器可以直接返回 JSON 数据、Promise，或使用 event.node.res.end() 发送响应。

server/api/hello.ts

export default defineEventHandler((event) => {
  return {
    hello: 'world'
  }
})

您现在可以在页面和组件中通用调用此 API：

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 路由将在 http://localhost:3000/hello 上可访问。

请注意，当前服务端路由不支持页面那样的完整动态路由功能。

服务端中间件

Nuxt 会自动读取 ~/server/middleware 目录中的文件，为您的项目创建服务端中间件。

中间件处理器会在每个请求到达其他服务端路由之前运行，用于添加或检查请求头、记录请求，或扩展事件请求对象。

中间件处理器不应返回任何内容（也不应关闭或响应请求），仅用于检查或扩展请求上下文，或抛出错误。

示例：

server/middleware/log.ts

export default defineEventHandler((event) => {
  console.log('新请求: ' + 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 插件', 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 {
      // 在路由处理器之前执行某些操作
      const response = await handler(event)
      // 在路由处理器之后执行某些操作
      return { response }
    } catch (err) {
      // 错误处理
      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(() => '测试 GET 处理器')

server/api/test.post.ts

export default defineEventHandler(() => '测试 POST 处理器')

根据上述示例，访问 /test：

GET 方法：返回 测试 GET 处理器
POST 方法：返回 测试 POST 处理器
其他方法：返回 405 错误

您还可以使用目录中的 index.[method].ts 来组织代码，适合创建 API 命名空间。

export default defineEventHandler((event) => {
  // 处理 `api/foo` 端点的 GET 请求
})

export default defineEventHandler((event) => {
  // 处理 `api/foo` 端点的 POST 请求
})

export default defineEventHandler((event) => {
  // 处理 `api/foo/bar` 端点的 GET 请求
})

捕获所有路由

捕获所有路由对于处理未匹配的路由非常有用。

例如，创建 ~/server/api/foo/[...].ts 文件将为所有未匹配其他路由处理器的请求注册一个捕获所有路由，例如 /api/foo/bar/baz。

server/api/foo/[...].ts

export default defineEventHandler((event) => {
  // event.context.path 获取路由路径：'/api/foo/bar/baz'
  // event.context.params._ 获取路由段：'bar/baz'
  return `默认 foo 处理器`
})

您可以通过 ~/server/api/foo/[...slug].ts 为捕获所有路由设置名称，并通过 event.context.params.slug 访问。

server/api/foo/[...slug].ts

export default defineEventHandler((event) => {
  // event.context.params.slug 获取路由段：'bar/baz'
  return `默认 foo 处理器`
})

请求体处理

server/api/submit.post.ts

export default defineEventHandler(async (event) => {
  const body = await readBody(event)
  return { body }
})

或者，使用 readValidatedBody 配合 Zod 等模式验证器以实现运行时和类型安全。

您现在可以使用以下方式通用调用此 API：

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 将抛出 405 方法不允许 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 内部服务器错误 HTTP 错误。

要返回其他错误码，请使用 createError 抛出异常：

server/api/validation/[id].ts

export default defineEventHandler((event) => {
  const id = parseInt(event.context.params.id) as number

  if (!Number.isInteger(id)) {
    throw createError({
      statusCode: 400,
      statusMessage: 'ID 应为整数',
    })
  }
  return '一切正常'
})

状态码

要返回其他状态码，请使用 setResponseStatus 工具函数。

例如，返回 202 已接受：

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
})

export default defineNuxtConfig({
  runtimeConfig: {
    githubToken: ''
  }
})

NUXT_GITHUB_TOKEN='<my-super-token>'

将 event 作为参数传递给 useRuntimeConfig 是可选的，但建议传递以获取在服务端路由运行时由环境变量覆盖的运行时配置。

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) => {
  // 安排一个后台任务，不阻塞响应
  event.waitUntil(timeConsumingBackgroundTask())

  // 立即向客户端发送响应
  return '完成'
});

高级用法

Nitro 配置

您可以在 nuxt.config 中使用 nitro 键直接设置 Nitro 配置。

这是一个高级选项。自定义配置可能会影响生产部署，因为随着 Nuxt 的次版本升级，Nitro 的配置接口可能会发生变化。

nuxt.config.ts

export default defineNuxtConfig({
  // https://nitro.build/config
  nitro: {}
})

阅读更多 Docs > Guide > Concepts > Server Engine.

嵌套路由

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('传统处理器')
})

通过 h3js/h3 支持传统处理器，但建议尽可能避免使用传统处理器。

server/middleware/legacy.ts

export default fromNodeMiddleware((req, res, next) => {
  console.log('传统中间件')
  next()
})

切勿将 next() 回调与异步或返回 Promise 的传统中间件结合使用。

服务端存储

Nitro 提供了一个跨平台的存储层。您可以通过 nitro.storage 或服务端插件配置额外的存储挂载点。

添加 Redis 存储示例：

使用 nitro.storage：

nuxt.config.ts

export default defineNuxtConfig({
  nitro: {
    storage: {
      redis: {
        driver: 'redis',
        /* redis 连接选项 */
        port: 6379, // Redis 端口
        host: "127.0.0.1", // Redis 主机
        username: "", // 需要 Redis >= 6
        password: "",
        db: 0, // 默认值为 0
        tls: {} // tls/ssl
      }
    }
  }
})

然后在您的 API 处理器中：

server/api/storage/test.ts

export default defineEventHandler(async (event) => {
  // 列出所有键
  const keys = await useStorage('redis').getKeys()

  // 设置一个键
  await useStorage('redis').setItem('foo', 'bar')

  // 删除一个键
  await useStorage('redis').removeItem('foo')

  return {}
})

了解更多关于 Nitro 存储层的信息。

或者，您可以使用服务端插件和运行时配置创建存储挂载点：

import redisDriver from 'unstorage/drivers/redis'

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

  // 从运行时配置或其他来源动态传递凭据
  const driver = redisDriver({
      base: 'redis',
      host: useRuntimeConfig().redis.host,
      port: useRuntimeConfig().redis.port,
      /* 其他 redis 连接选项 */
    })

  // 挂载驱动
  storage.mount('redis', driver)
})

export default defineNuxtConfig({
  runtimeConfig: {
    redis: { // 默认值
      host: '',
      port: 0,
      /* 其他 redis 连接选项 */
    }
  }
})

Was this helpful?

Report an issue or Edit this page on GitHub

public

public/ 目录用于提供你网站的静态资产。

shared

使用 shared/ 目录在 Vue 应用和 Nitro 服务端之间共享功能。