Nuxt 会自动扫描~/server/api、~/server/routes 和~/server/middleware 目录中的文件，以注册 API 和服务器处理程序以支持 HMR。
每个文件都应该导出一个用 defineEventHandler() 定义的默认函数。
处理程序可以直接返回 JSON 数据、Promise 或使用 event.node.res.end() 发送响应。
基础示例
在 server/api 中创建一个新文件 server/api/hello.ts:
export default defineEventHandler((event) => {
return {
api: 'works'
}
})
您现在可以使用 await $fetch('/api/hello') 普遍调用此 API。
服务器路由
~/server/api 中的文件在其路由中自动以 /api 为前缀。
要添加不带 /api 前缀的服务器路由，您可以将它们放入 ~/server/routes 目录。
示例:
export default defineEventHandler(() => 'Hello World!')
在上面的示例中，可以在 http://localhost:3000/hello 访问 /hello 路由。
请注意，当前服务器路由不支持动态路由的完整功能，如pages。
服务器中间件
Nuxt 会自动读取 ~/server/middleware 中的任何文件，为您的项目创建服务器中间件。
中间件处理程序将在任何其他服务器路由之前针对每个请求运行，以添加或检查标头、记录请求或扩展事件的请求对象。
中间件处理程序不应该返回任何东西(也不关闭或响应请求)并且只检查或扩展请求上下文或抛出错误。
示例:
export default defineEventHandler((event) => {
console.log(`New request: ${event.node.req.url}`)
})
export default defineEventHandler((event) => {
event.context.auth = { user: 123 }
})
服务器插件
Nuxt 将自动读取 ~/server/plugins 目录中的所有文件并将它们注册为 Nitro 插件。 这允许扩展 Nitro 的运行时行为并连接到生命周期事件中。
示例:
export default defineNitroPlugin((nitroApp) => {
console.log('Nitro plugin', nitroApp)
})
服务器实用程序
服务器路由由 unjs/h3 提供支持，它带有一组方便的助手。
您可以自己在 ~/server/utils 目录中添加更多助手。
例如，您可以定义一个自定义处理程序实用程序，该实用程序包装原始处理程序并在返回最终响应之前执行其他操作。
Example:
import type { EventHandler } from 'h3'
export function defineWrappedResponseHandler(handler: EventHandler) {
return defineEventHandler(async (event) => {
try {
// 在路由处理程序之前做一些事情
const response = await handler(event)
// 在路由处理程序之后做一些事情
return { response }
}
catch (err) {
// 错误处理
return { err }
}
})
}
服务器类型
此功能可从 Nuxt >= 3.5 开始使用
为了提高 IDE 中nitro和vue自动导入之间的清晰度，您可以添加包含以下内容的~/server/tsconfig.json
{
"extends": "../.nuxt/tsconfig.server.json"
}
尽管现在在类型检查(nuxi typecheck)时不会考虑这些值，但您应该在 IDE 中获得更好的类型提示。
基础用法示例
匹配路由参数
服务器路由可以在文件名中使用括号内的动态参数
例如 /api/hello/[name].ts 并通过 event.context.params 访问。
export default defineEventHandler(event => `Hello, ${event.context.params.name}!`)
您现在可以使用 await $fetch('/api/hello/nuxt') 普遍调用此 API 并获得 Hello, nuxt!。
匹配 HTTP 方法
句柄文件名可以加上 .get、.post、.put、.delete 等后缀，以匹配请求的 [HTTP 方法](https://developer.mozilla.org/en- 美国/文档/网络/HTTP/方法)。
export default defineEventHandler(() => 'Test get handler')
export default defineEventHandler(() => 'Test post handler')
给定上面的示例，获取 /test 使用：
- GET method: Returns
Test get handler - POST method: Returns
Test post handler - Any other method: Returns 405 error
包罗万象的路线
Catch-all 路由有助于回退路由处理。 例如，创建一个名为 ~/server/api/foo/[...].ts 的文件将为所有不匹配任何路由处理程序的请求注册一个包罗万象的路由，例如 /api/foo/bar/baz。
export default defineEventHandler(() => `Default foo handler`)
export default defineEventHandler(() => `Default api handler`)
处理带有正文的请求
export default defineEventHandler(async (event) => {
const body = await readBody(event)
return { body }
})
您现在可以使用 $fetch('/api/submit', { method: 'post', body: { test: 123 } }) 普遍调用此 API。
我们在文件名中使用 submit.post.ts 只是为了将请求与可以接受请求正文的 POST 方法匹配。 在 GET 请求中使用 readBody 时，readBody 将抛出 405 Method Not Allowed HTTP 错误。
使用查询参数处理请求
基础的请求方式 /api/query?param1=a¶m2=b
export default defineEventHandler((event) => {
const query = getQuery(event)
return { a: query.param1, b: query.param2 }
})
错误处理
如果未抛出任何错误，将返回状态代码“200 OK”。
任何未捕获的错误都将返回“500 Internal Server Error”HTTP 错误。
要返回其他错误代码，请使用 createError 抛出异常
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
export default defineEventHandler((event) => {
setResponseStatus(event, 202)
})
访问运行时配置
export default defineEventHandler((event) => {
const config = useRuntimeConfig()
return { key: config.KEY }
})
访问请求 Cookie
export default defineEventHandler((event) => {
const cookies = parseCookies(event)
return { cookies }
})
高级用法示例
Nitro 配置
您可以使用 nuxt.config 中的 nitro 键直接设置 Nitro 配置。
这是一个高级选项。 自定义配置会影响生产部署，因为当 Nitro 在 Nuxt 的 semver-minor 版本中升级时，配置界面可能会随着时间而改变。
export default defineNuxtConfig({
nitro: {}
})
使用嵌套路由器
import { createRouter, defineEventHandler, useBase } from 'h3'
const router = createRouter()
router.get('/test', defineEventHandler(() => 'Hello World'))
export default useBase('/api/hello', router.handler)
发送流(实验)
这是一项实验性功能，仅在 Node.js 环境中可用。
import fs from 'node:fs'
import { sendStream } from 'h3'
export default defineEventHandler((event) => {
return sendStream(event, fs.createReadStream('/path/to/file'))
})
发送重定向
export default defineEventHandler((event) => {
return sendRedirect(event, '/path/redirect/to', 302)
})
返回传统的处理程序或中间件
export default fromNodeMiddleware((req, res) => {
res.end('Legacy handler')
})
使用 unjs/h3 可以提供旧版支持，但建议尽可能避免使用旧版处理程序。
export default fromNodeMiddleware((req, res, next) => {
console.log('Legacy middleware')
next()
})
切勿将 next() 回调与 async 或返回 Promise 的遗留中间件结合使用！
服务器存储
Nitro 提供了一个跨平台的存储层。
为了配置额外的存储挂载点，您可以使用 nitro.storage。
使用 Redis 示例：
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
}
}
}
})
在 server/api/test.post.ts 中创建一个新文件：
export default defineEventHandler(async (event) => {
const body = await readBody(event)
await useStorage().setItem('redis:test', body)
return 'Data is set'
})
在 server/api/test.get.ts 中创建一个新文件：
export default defineEventHandler(async (event) => {
const data = await useStorage().getItem('redis:test')
return data
})
在 app.vue 中创建一个新文件：
<script setup lang="ts">
const { data: resDataSuccess } = await useFetch('/api/test', {
method: 'post',
body: { text: 'Nuxt is Awesome!' }
})
const { data: resData } = await useFetch('/api/test')
</script>
<template>
<div>
<div>Post state: {{ resDataSuccess }}</div>
<div>Get Data: {{ resData.text }}</div>
</div>
</template>