企业官网建设流程全解析

useRequestEvent 完全指南：在 Nuxt 服务端安全访问当前请求事件

【免费下载链接】nuxtthe full-stack Vue framework项目地址: https://gitcode.com/GitHub_Trending/nu/nuxt

useRequestEvent是 Nuxt 暴露给应用层的服务端组合式函数，用于在页面、组件、插件与中间件中读取当前**传入请求（incoming request）**的事件对象。本文以 Nuxt 官方 API 文档 为主体，结合本仓库中该函数的源码实现、类型契约、Nitro 渲染链路与真实测试用例，完整讲解它的返回值、生命周期、可用环境、底层数据结构，以及一组以它为基础构建的派生 API（useRequestHeader、useRequestURL、setResponseStatus等）。读完你将能在 SSR 场景下正确取用请求路径、请求头与响应对象，并避开“浏览器端拿到undefined”的常见陷阱。

一、它是什么：服务端请求事件的统一入口

在 Nuxt 的 Nuxt context（Nuxt 上下文） 内，可以调用useRequestEvent访问正在处理的请求事件：

// 获取底层请求事件 const event = useRequestEvent() // 获取请求 URL（路径） const url = event?.path

该函数自 Nuxt 3.0.0 起提供，完整实现位于 packages/nuxt/src/app/composables/ssr.ts：

/** @since 3.0.0 */ export function useRequestEvent (nuxtApp?: NuxtApp): RequestEvent | undefined { if (import.meta.client) { return } nuxtApp ||= useNuxtApp() return nuxtApp.ssrContext?.event }

从实现可以看到三个关键设计：

1. 接收可选的nuxtApp参数——省略时会通过useNuxtApp()取得当前应用实例，这在层级（layer）扩展或自定义 Nuxt 实例场景下提供了灵活性；
2. 返回值类型是RequestEvent | undefined——原因稍后详解；
3. 实现只有三行：在服务端读取nuxtApp.ssrContext?.event并返回。

官方文档在 source 链接 处的注释也点明了事件对象的真实类型：“由所配置的server.builder声明（在@nuxt/nitro-server下即为 h3 的H3Event）”。

它属于 Nuxt 自动导入的组合式函数集合（见 packages/nuxt/src/imports/presets.ts 中与useRequestHeader、setResponseStatus等并列的注册列表），因此在.vue、插件、中间件中无需显式import即可直接调用。

一个最常用的守卫：浏览器中返回undefined

官方文档专门用 tip 提示：

在浏览器中，useRequestEvent将返回undefined。

这与源码第一行的if (import.meta.client) { return }完全对应——一旦代码被打包进客户端 bundle，函数会立即返回，不读取任何上下文。因此所有对该函数结果的访问都应使用可选链（?.）或判空，例如文档示例的event?.path，以及 setResponseStatus 文档 中“先在 if 中判空再使用”的写法。

二、事件从哪里来：ssrContext.event 的生命周期

useRequestEvent的本质是读取nuxtApp.ssrContext。在 Nuxt 类型定义 packages/nuxt/src/app/types.ts 中，NuxtSSRContext明确声明了event字段：

export interface NuxtSSRContext extends SSRContext { url: string event: RequestEvent runtimeConfig: RuntimeConfig // ... }

那么这个ssrContext是如何携带上event的？答案在服务端渲染链路中。Nitro 渲染器在每次请求进入时调用 createSSRContext(event)，把 Nitro 为当前请求构造的H3Event放入 ssrContext：

export function createSSRContext (event: H3Event): NuxtSSRContext { const url = event.url.pathname + event.url.search + urlHash(event.url) const ssrContext: NuxtSSRContext = { url, event, runtimeConfig: useRuntimeConfig() as NuxtSSRContext['runtimeConfig'], noSSR: /* ... */, head: createHead(unheadOptions), // ... } // ... }

同样的机制也用于 Nuxt Island（组件岛）的服务端渲染——packages/nitro-server/src/runtime/handlers/island.ts 在renderIsland中执行{ ...createSSRContext(event), islandContext }后再调用renderer.renderToString(ssrContext)。这意味着无论是整页 SSR 还是组件岛渲染，凡是经过 Nitro 服务端渲染的代码路径，useRequestEvent都能拿到与当前请求一一对应的事件对象。

随后 packages/nuxt/src/app/nuxt.ts 在创建 NuxtApp 时会做反向接线：把nuxtApp挂到ssrContext.nuxt、把 payload 与运行时配置挂到ssrContext.payload与ssrContext.config，从而让应用侧组合式函数既能“向上”读事件，也能把渲染结果“向下”写回。

三、事件对象的字段契约与跨端类型

useRequestEvent的返回值类型RequestEvent定义在 packages/schema/src/types/server.ts，并非写死的单一结构，而是通过模块注册表解析出来的：

/** * 回退请求事件形态，仅用 Web 标准描述。 * 当没有 server builder 贡献事件类型时使用。 */ export interface RequestEventFallback { readonly req: Request url: URL readonly res: { status?: number statusText?: string readonly headers: Headers } readonly context: Record<string, unknown> } /** 由 server.builder 声明的 RequestEvent，未声明时回退为 RequestEventFallback */ export type RequestEvent = ResolveRequestEvent<ServerTypes>

从中可以提炼出事件对象在 Web 标准层面的核心契约：

而在默认的 Nitro 构建下，@nuxt/nitro-server会在 packages/nitro-server/src/augments.ts 通过declare module '@nuxt/schema'把ServerTypes['event']声明为 h3 的H3Event，所以此时useRequestEvent()的实际类型就是H3Event——它提供了path、method等更便利的属性，文档示例中的event?.path依赖的正是这一点。

这一类型推导在测试中被严格校验：在 test/fixtures/basic-types/app/app-types.ts 中可以看到expectTypeOf(useRequestEvent()).toEqualTypeOf<H3Event | undefined>()的类型断言。而 test/nuxt/composables.test.ts 则从运行时的角度验证了useRequestEvent()在客户端环境的返回值是undefined。

四、能做什么：读取请求、改写响应

拿到事件对象后，最常见操作无非三类：读请求头、读请求元信息、写响应头/状态码。仓库中的 cookie 实现是把这三类能力用在同一事件对象上的典型例子：

• 读取 Cookie 时从请求头解析：packages/nuxt/src/app/composables/cookie.ts 中parse(useRequestEvent()!.req.headers.get('cookie') || '', opts)；
• 写出/删除 Cookie 时操作响应头：同文件通过event.res.headers.getSetCookie()、event.res.headers.set('set-cookie', ...)、event.res.headers.delete('set-cookie')完成，见 packages/nuxt/src/app/composables/cookie.ts。

也就是说，useRequestEvent本质上把“当前请求/响应的全部读写入口”收敛到了一个对象上，供应用层所有服务端能力复用。你也可以自己直接使用：

// 读取单个请求头 const lang = useRequestEvent()?.req.headers.get('accept-language') // 遍历全部请求头（对象形式） const headers = event ? Object.fromEntries(event.req.headers.entries()) : {}

五、真实使用模式（源自仓库 fixture 与教程）

5.1 在中间件中读取请求头做逻辑分流

Nuxt 路由中间件在服务端渲染时也会执行，此时可以用useRequestEvent感知请求头。基础 fixture 的 redirect.global.ts 展示了这种模式——根据请求头trailing-slash决定是否改写路径：

export default defineNuxtRouteMiddleware((to) => { if (useRequestEvent()?.req.headers.get('trailing-slash') && to.fullPath.endsWith('/')) { // 服务端请求头触发的重定向逻辑 } })

注意：这类逻辑在客户端导航时同样会执行，但因客户端useRequestEvent()返回undefined，可选链会让判断自然失效，从而天然只作用于 SSR 首屏。

5.2 在页面/插件中写入自定义响应头

自定义响应头是 A/B 测试、埋点标识、安全策略等需求的常用手段。fixture 的模块运行时页面通过非空断言拿到事件后写入x-extend头，见 modules/runtime/page.vue。常规写法如下：

const event = useRequestEvent() if (event) { event.res.headers.set('x-custom', 'server-value') }

5.3 流式响应/错误页中设置状态码

仓库测试覆盖了“为某条路由返回 418”的用法，见 test/fixtures/ssr-streaming/pages/late-status.vue：

setResponseStatus(useRequestEvent()!, 418)

setResponseStatus第一个参数就是RequestEvent，其源码（ssr.ts）在传入事件时直接修改event.res.status与event.res.statusText。若你只传数字不传事件，它内部同样会调用useRequestEvent()兜底——新版签名把事件作为第一参数也正是为了让调用点更显式。

5.4 把原始请求头透传给内部数据请求（Cookie 透传）

在 getting-started 的数据获取教程 中给出了一个经典实战：SSR 阶段请求内部 API 时，把响应set-cookie原样附加到当前请求事件上，从而在无刷新场景下把服务端设置的 Cookie 带回浏览器：

export const fetchWithCookie = async (event, url) => { const res = await $fetch.raw(url) const cookies = res.headers.getSetCookie() for (const cookie of cookies) { event.res.headers.append('set-cookie', cookie) } return res._data }

<script setup lang="ts"> const event = useRequestEvent() const { data: result } = await useAsyncData(() => fetchWithCookie(event!, '/api/with-cookie')) </script>

这正是“在 setup 顶层捕获事件、把请求级信息传入异步数据函数”的标准姿势。类似的“插件内读取事件”用法还可见于错误递归保护插件 error.server.ts 与 CSP nonce 插件 test/fixtures/ssr-streaming/plugins/csp-nonce.ts。

5.5 将事件传给其他请求级工具

事件对象还可以作为参数传给getRouteRules等请求级 API——类型 fixture 中即存在getRouteRules(useRequestEvent()!)的调用（见 basic-types/app/app-types.ts），用于取得当前路由匹配到的规则。

六、派生 API 家族：站在 useRequestEvent 之上

许多服务端相关组合式函数内部都依赖useRequestEvent，理解了它，就等于理解了这一族 API 的地基。下表整理了它们的入口文档与实现位置：

值得说明的两个实现细节：

• useRequestHeaders读取的其实是Object.fromEntries(event.req.headers.entries())（见 ssr.ts），并以小写 key 组织返回；源码注释已推荐“若只要单个或少数请求头，直接通过useRequestEvent().req.headers获取”，避免不必要的整体拷贝。
• useRequestFetch对转发头做了白名单过滤（见 ssr.ts），accept、content-type、host、transfer-encoding等 hop-by-hop/载荷类头不会被转发，以防止子请求因带载荷头而出错。它同样基于useRequestEvent找到当前事件并缓存requestFetchers。

七、何时返回 undefined：边界与注意事项汇总

结合源码、类型与官方文档，把容易踩坑的边界条件归纳如下：

1. 浏览器/客户端任何时刻：函数直接return，永远为undefined。判断“是否在服务端”应使用import.meta.server或直接判空event，二者不能混为一谈——在客户端import.meta.server为假，但你仍可能调用一个期望事件存在的代码分支。
2. 客户端导航（hydration 之后）：页面切换不再经过 Nitro 渲染，任何依赖该函数的 SSR 专用逻辑（读原始请求头、改响应状态码）都不会生效。
3. Nitro 服务端路由（server/api、server/routes）中：从渲染链路看，这些处理器运行在 Nuxt 应用（ssrContext）被创建之前，事件对象已由defineEventHandler((event) => ...)直接作为参数传入，因此无需也没有可靠的ssrContext可读；请直接使用参数里的event。
4. 值的作用域是“单次请求”：ssrContext为每次服务端请求新建，useRequestEvent拿到的事件绝不可跨请求缓存或写入全局模块级状态，否则会造成请求间数据串扰。
5. 类型上永远是RequestEvent | undefined：即使服务端场景，若在某段缺少ssrContext的代码（例如未进入渲染的初始化阶段）调用，也可能得到undefined。稳妥做法是判空后再操作，参考 setResponseStatus 文档 中if (event) { setResponseStatus(event, 404) }的写法。

八、结语

useRequestEvent虽是一个三行的组合式函数，却是 Nuxt“应用层 ↔ Nitro 服务端”之间请求信息的唯一通道：读取请求头与路径、写入自定义响应头、设置状态码、透传 Cookie，乃至useRequestFetch、useResponseHeader、setResponseStatus等一整族 SSR 工具，最终都汇聚到ssrContext.event这一个对象上。掌握它的返回值语义（服务端H3Event、浏览器undefined）、生命周期来源（createSSRContext每次请求注入）与字段契约（req/res/url/context），即可在 SSR 首屏渲染中安全、精确地操作“属于这一次请求”的完整 HTTP 上下文。

如需继续深入，可顺次阅读 Nuxt 上下文说明、useRequestURL 实现、RequestEvent 类型注册机制，以及在 ssr.ts 中与其共享同一文件的其他 SSR 组合式函数源码。

【免费下载链接】nuxtthe full-stack Vue framework项目地址: https://gitcode.com/GitHub_Trending/nu/nuxt