0Pricing
Vue Academy · 课时

Nuxt 服务端路由与 API 端点

server/api/ 目录、defineEventHandler()、H3 工具、中间件，以及错误处理

Nuxt 服务端路由与 API 端点 是 CoddyKit 上的免费 Vue Academy 课时。 这是第 3 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 Vue Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Vue Academy 课程共包含 4 节课。

Nuxt 是全栈框架

Nuxt 3 内置服务器引擎（Nitro）。借助 server/ 目录，您可以将 API 端点与 page 放在一起构建；对于许多 app，无需单独的后端。

server/api 目录

server/api/ 中的文件会成为 /api 下的 API 路由。server/api/hello.ts 会在 /api/hello 响应。

server/
  api/
    hello.ts   ->  /api/hello
    posts.ts   ->  /api/posts

defineEventHandler

每个服务器路由都会导出一个使用 defineEventHandler 创建的处理函数。它返回的任何内容都会作为响应发送，并自动序列化为 JSON。

// server/api/hello.ts
export default defineEventHandler((event) => {
  return { message: 'Hello from the server' }
})

HTTP 方法后缀

在文件名中添加方法后缀即可限制其适用范围。users.get.ts 处理 GET，users.post.ts 处理 POST。不添加后缀时，该路由会响应任何方法。

server/api/
  users.get.ts   ->  GET /api/users
  users.post.ts  ->  POST /api/users

读取查询参数

使用 getQuery 辅助函数从事件中读取 URL 查询字符串。

export default defineEventHandler((event) => {
  const query = getQuery(event)
  return { search: query.q }
})

读取请求正文

对于 POST/PUT 请求，readBody 会解析传入的 JSON 正文。它是异步的，因此请使用 await。

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

动态服务器路由

服务器端同样支持使用方括号命名的文件。server/api/users/[id].get.ts 使用 getRouterParam 读取 id。

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

抛出 HTTP 错误

使用 createError 返回带有状态码和消息的规范 HTTP 错误响应，而不要直接抛出普通错误。

export default defineEventHandler((event) => {
  const id = getRouterParam(event, 'id')
  if (!id) {
    throw createError({ statusCode: 400, statusMessage: 'Missing id' })
  }
})

H3 事件对象

event 参数来自 H3，即 Nitro 的 HTTP 框架。它携带请求和响应，是所有辅助函数的入口。

设置状态和标头

当仅返回一个值不足以满足需求时，可以使用 setResponseStatus 和 setHeader 等辅助函数控制响应。

export default defineEventHandler((event) => {
  setResponseStatus(event, 201)
  setHeader(event, 'Cache-Control', 'no-cache')
  return { created: true }
})

从 page 调用您自己的 API

在 page 中，使用 useFetch 或 $fetch 获取您自己的端点。在 SSR 期间，Nuxt 会直接调用处理函数，跳过 HTTP 往返。

const { data } = await useFetch('/api/posts')

快速检查

测试您对 Nuxt 服务器路由的掌握情况。

回顾

您已经学习了 Nuxt 服务器路由：

  • server/api/ 中的文件会成为 API 端点。
  • defineEventHandler 用于定义处理函数；其返回值就是响应。
  • .get.ts/.post.ts 后缀用于限定 HTTP 方法。
  • 在 H3 事件中使用 getQuery、readBody、getRouterParam 和 createError。

常见问题解答

「Nuxt 服务端路由与 API 端点」课时是免费的吗？

是的 — 「Nuxt 服务端路由与 API 端点」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Vue Academy 课程的其余内容，请升级到 CoddyKit PRO。 Vue Academy 课程共包含 4 节课。

「Nuxt 服务端路由与 API 端点」这节课中我会学到什么？

server/api/ 目录、defineEventHandler()、H3 工具、中间件，以及错误处理 你通过在浏览器中直接运行的动手代码来练习 Vue Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Vue Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Vue Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 3 节课，共 4 节。

「Nuxt 服务端路由与 API 端点」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Vue Academy 课中编写并运行代码吗？

能。每节 Vue Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

  1. Nuxt 3 项目结构与基于文件的路由
  2. 数据获取：useFetch 与 useAsyncData
  3. Nuxt 服务端路由与 API 端点
  4. SSR、SSG 与 SPA 模式
← 返回 Vue Academy