服务端能力与 API 路由

Nuxt 3 不只是一个“让 Vue 支持 SSR”的框架，它还内置了一套轻量但实用的服务端运行时，让你可以直接在项目里编写后端接口，而不再需要单独起一个 Node 服务。这就是 server/ 目录下的 API 路由 和 服务端中间件 体系。

为什么需要在 Vue 项目里写服务端代码

传统前后端分离项目中，前端开发经常需要等待后端接口就绪，或者自己用 Mock 工具造假数据。而 Nuxt 3 的服务端能力让你可以：

快速编写 BFF（Backend For Frontend）接口：聚合多个后端接口、裁剪字段、处理格式，直接返回前端需要的数据结构。
实现代理转发：隐藏真实后端地址，解决跨域问题。
处理第三方回调：比如 OAuth 登录流程、支付通知接收。
读取文件系统、操作数据库：在需要轻量全栈能力的场景下（个人项目、内部工具），无需再搭建一整套后端框架。

API 路由：在 `server/api/` 下写接口

Nuxt 3 会自动扫描 server/api/ 目录中的文件，将文件名映射为接口路径。一个最简单的示例：

// server/api/hello.ts
export default defineEventHandler((event) => {
  return {
    message: 'Hello from Nuxt API!',
    timestamp: Date.now()
  }
})

启动项目后，访问 /api/hello 就会得到这段 JSON 响应。defineEventHandler 是 Nuxt 提供的标准函数，它的参数 event 包含了请求信息，可以通过辅助函数读取：

// server/api/user/[id].ts
export default defineEventHandler((event) => {
  const id = getRouterParam(event, 'id')   // 获取路径参数
  const query = getQuery(event)            // 获取查询参数 ?name=xxx
  const body = await readBody(event)       // 获取 POST 请求体
  const headers = getHeaders(event)        // 获取请求头
  
  // 验证、查询数据库、调用第三方 API...
  return { id, query, body }
})

路径规则：

server/api/todo.ts → /api/todo
server/api/todo/index.ts → /api/todo
server/api/todo/[id].ts → /api/todo/123
server/api/todo/[...catchall].ts → 匹配所有 /api/todo/* 的路径

这让 API 的组织非常直观，不需要额外编写路由注册代码。

服务端中间件：在请求到达前拦截

除了 API 路由，你还可以在 server/middleware/ 中添加中间件，对所有服务端请求进行预处理。比如验证 Token、记录日志：

// server/middleware/auth.ts
export default defineEventHandler((event) => {
  const token = getHeader(event, 'authorization')
  if (event.path.startsWith('/api/protected') && !token) {
    throw createError({ statusCode: 401, message: '未授权' })
  }
  // 验证通过，继续执行后续逻辑
})

中间件按文件名顺序执行，适合做全局守卫、CORS 设置、性能监控等。

服务端数据获取：直通组件

Nuxt 3 的 useFetch 和 useAsyncData 在 SSR 模式下会自动在服务端执行一次，并将数据脱水传递给客户端。但如果你需要在服务端做更复杂的逻辑（如权限校验、多接口聚合），完全可以在 server/api/ 中封装好，然后组件里直接调：

<script setup>
const { data: posts } = await useFetch('/api/posts')
</script>

这套链路让前端开发者可以自己闭环从接口到页面的完整流程，减少依赖阻塞。

实用注意事项

部署环境：Nuxt 3 服务端代码运行在 Node.js 环境，部署时可以用 node .output/server/index.mjs 启动，也可以部署到 Cloudflare Workers、Vercel、Netlify 等边缘平台（Nuxt 3 内置了多平台预设）。
安全性：API 路由默认仅在服务端运行，不会暴露到客户端。但要注意不要在事件处理函数中不慎返回敏感信息（如数据库密码）。
性能：这段服务端逻辑是胶水层，适合轻量计算和聚合，不建议重计算阻塞请求。如需处理大量数据，考虑异步任务队列或专用后端服务。
数据库访问：可以直接在 API 路由中使用 Prisma、Mongoose 等 ORM，但注意 server/ 下的代码会被打包成服务端 bundle，引入的客户端库可能导致包体积增大，需评估。

总结

Nuxt 3 的服务端能力不是要替代传统后端，而是为前端开发者提供了一层便捷的“自留地”：

API 路由让你能用写 Vue 组件的熟悉感来写轻量接口。
服务端中间件让你能拦截和预处理请求。
它们与 Vue 的数据获取、SSR 流程天然集成，真正实现“一套工程搞定前后端”。

对于中小型项目、内部工具、或者需要快速验证原型的场景，这个能力极具实用价值，减少了前后端分离带来的沟通和等待成本。

为什么需要在 Vue 项目里写服务端代码

API 路由：在 server/api/ 下写接口

服务端中间件：在请求到达前拦截

服务端数据获取：直通组件

实用注意事项

总结

API 路由：在 `server/api/` 下写接口