进阶篇三 Nuxt4 Nitro 引擎：Nuxt 的服务端核心

个人网站
Nuxt 3 以后，服务端能力大幅提升，这要归功于 Nitro 引擎。它不只是个构建工具，而是一个完整的服务端框架——支持 API 路由、中间件、存储抽象、多种部署目标……今天深入了解 Nitro。

一、Nitro 是什么

Nitro 是 Nuxt 的服务端引擎，负责：

• 服务端渲染：执行 Vue 组件的 SSR
• API 路由：处理/api/*请求
• 中间件：请求拦截和处理
• 存储抽象：统一的存储接口
• 构建产物：生成可部署的服务器代码

简单说：Nuxt 前端 + Nitro 后端 = 全栈应用

二、目录结构

Nitro 相关目录：

server/ ├── api/ # API 路由 │ ├── hello.ts # /api/hello │ └── users/ │ └── [id].ts # /api/users/:id ├── routes/ # 服务端路由 │ └── sitemap.xml.ts # /sitemap.xml ├── middleware/ # 服务端中间件 │ └── auth.ts ├── plugins/ # Nitro 插件 │ └── db.ts └── utils/ # 服务端工具函数 └── format.ts

三、API 路由

创建 API 接口非常简单：

// server/api/hello.tsexportdefaultdefineEventHandler(()=>{return{message:'Hello World'}})

访问/api/hello，返回：

{"message":"Hello World"}

动态路由

// server/api/articles/[id].tsexportdefaultdefineEventHandler((event)=>{constid=getRouterParam(event,'id')return{id,title:`文章${id}`,content:'...'}})

访问/api/articles/123：

{"id":"123","title":"文章 123","content":"..."}

请求方法

// server/api/articles.tsexportdefaultdefineEventHandler(async(event)=>{constmethod=getMethod(event)switch(method){case'GET':returngetArticles()case'POST':constbody=awaitreadBody(event)returncreateArticle(body)case'PUT':constupdateData=awaitreadBody(event)returnupdateArticle(updateData)case'DELETE':returndeleteArticle()}})

更优雅的方式是拆分文件：

server/api/articles/ ├── index.get.ts # GET /api/articles ├── index.post.ts # POST /api/articles └── [id]/ ├── get.ts # GET /api/articles/:id ├── put.ts # PUT /api/articles/:id └── delete.ts # DELETE /api/articles/:id

// server/api/articles/index.get.tsexportdefaultdefineEventHandler(()=>{returngetArticles()})// server/api/articles/index.post.tsexportdefaultdefineEventHandler(async(event)=>{constbody=awaitreadBody(event)returncreateArticle(body)})

四、请求处理

获取请求信息

exportdefaultdefineEventHandler((event)=>{// 请求方法constmethod=getMethod(event)// 请求 URLconsturl=getRequestURL(event)// 请求头constheaders=getHeaders(event)constauth=getHeader(event,'authorization')// 查询参数constquery=getQuery(event)// Cookieconstcookies=parseCookies(event)consttoken=getCookie(event,'token')// 请求体constbody=awaitreadBody(event)// 客户端 IPconstip=getRequestIP(event)return{method,url,query}})

设置响应

exportdefaultdefineEventHandler((event)=>{// 设置状态码setResponseStatus(event,201)// 设置响应头setResponseHeaders(event,{'X-Custom-Header':'value'})// 设置 CookiesetCookie(event,'token','xxx',{httpOnly:true,maxAge:60*60*24*7})// 删除 CookiedeleteCookie(event,'token')// 重定向returnsendRedirect(event,'/login')// 返回 JSONreturn{success:true}})

五、中间件

服务端中间件会拦截所有请求：

// server/middleware/auth.tsexportdefaultdefineEventHandler((event)=>{consturl=getRequestURL(event)// 只拦截需要认证的路由if(url.pathname.startsWith('/api/protected')){consttoken=getHeader(event,'authorization')if(!token){throwcreateError({statusCode:401,message:'Unauthorized'})}// 验证 tokenconstuser=verifyToken(token)event.context.user=user}})

六、存储抽象

Nitro 提供统一的存储接口，支持多种后端：

// server/api/views.tsexportdefaultdefineEventHandler(async(event)=>{conststorage=useStorage()// 读取constviews=awaitstorage.getItem('views')||0// 写入awaitstorage.setItem('views',views+1)return{views}})

配置存储后端：

// nuxt.config.tsexportdefaultdefineNuxtConfig({nitro:{storage:{// 内存存储（开发环境）cache:{driver:'memory'},// Redis（生产环境）redis:{driver:'redis',url:'redis://localhost:6379'},// 文件系统data:{driver:'fs',base:'./data'}}}})

使用指定存储：

// 使用 redis 存储conststorage=useStorage('redis')awaitstorage.setItem('user:1',{name:'Alice'})// 使用文件存储constfsStorage=useStorage('data')awaitfsStorage.setItem('config.json',{theme:'dark'})

七、数据库集成

以 Prisma 为例：

pnpmaddprisma @prisma/client npx prisma init

// prisma/schema.prisma model Article { id Int @id @default(autoincrement()) title String content String createdAt DateTime @default(now()) }

// server/utils/db.tsimport{PrismaClient}from'@prisma/client'constprisma=newPrismaClient()exportconstusePrisma=()=>prisma

// server/api/articles/index.get.tsexportdefaultdefineEventHandler(async()=>{constprisma=usePrisma()returnprisma.article.findMany()})

八、计划任务

Nitro 支持定时任务：

// server/tasks/cleanup.tsexportdefaultdefineTask({name:'cleanup:expired-sessions',run:async()=>{conststorage=useStorage()constsessions=awaitstorage.getKeys('session:')for(constkeyofsessions){constsession=awaitstorage.getItem(key)if(session?.expiresAt<Date.now()){awaitstorage.removeItem(key)}}return{result:'success'}}})

配置执行间隔：

// nuxt.config.tsexportdefaultdefineNuxtConfig({nitro:{scheduledTasks:{'0 * * * *':'cleanup:expired-sessions'// 每小时执行}}})

九、缓存控制

响应缓存

// server/api/articles/[id].tsexportdefaultdefineCachedEventHandler(async(event)=>{constid=getRouterParam(event,'id')constarticle=awaitgetArticle(id)returnarticle},{maxAge:60*60,// 缓存 1 小时swr:true,// 启用 SWRvaries:['Authorization']// 按认证状态分别缓存})

缓存失效

// 手动清除缓存exportdefaultdefineEventHandler(async(event)=>{constcache=useStorage('cache')awaitcache.removeItem('api:articles:123')return{cleared:true}})

十、错误处理

exportdefaultdefineEventHandler((event)=>{constid=getRouterParam(event,'id')if(!id){throwcreateError({statusCode:400,message:'Missing id parameter'})}constarticle=getArticle(id)if(!article){throwcreateError({statusCode:404,message:'Article not found'})}returnarticle})

全局错误处理：

// server/middleware/error.tsexportdefaultdefineEventHandler((event)=>{event.node.res.on('finish',()=>{conststatus=event.node.res.statusCodeif(status>=400){console.error(`Error${status}:${getRequestURL(event)}`)}})})

总结

Nitro 核心能力：

功能	用途
API 路由	创建后端接口
中间件	请求拦截
存储抽象	统一存储接口
缓存	提升性能
计划任务	定时执行
多部署目标	部署到任意平台

有了 Nitro，Nuxt 不只是前端框架，而是全栈框架。下一篇聊聊 Server Routes 的实战应用。

相关文章

入门篇三：Nuxt4组件自动导入：写代码少敲一半字

入门篇二：Nuxt 4路由自动生成：告别手动配置路由的日子

延伸阅读

nuxt4完整系列，持续更新中。。，欢迎来逛逛

---

内容有帮助？点赞、收藏、关注三连！评论区等你 💪