用途:整理构建 Nuxt 应用时遵循的约定,覆盖 Nuxt 运行时行为、Nitro 服务端路由、数据获取,以及依赖 Nuxt 构建期集成的类型模式。非 Nuxt 的 Vue 组件约定(组件结构、props、emits、样式)不属于此范围。
主要能力与规则:
- 从 #imports 导入 Nuxt API。当 Nuxt 文件需要框架 API 时,显式从 #imports 导入,不要从 #app 导入。即便关闭自动导入,每个 Nuxt 组合式函数仍需显式导入。useRoute、useFetch、navigateTo、definePageMeta、useState、useCookie 等运行时 API 都从 #imports 导入。
- 通过 Nitro handler 为内部 fetch 提供类型。Nuxt 会根据 Nitro handler 的返回类型推断自身 /api/... 路由的响应类型,应使用该推断,而不在调用处重复写泛型。每个 Nitro handler 都要标注显式返回类型,通常是 Promise<YourResponse>;调用内部路由用 useFetch('/api/...') 且不带响应泛型。需要命令式内部请求时,用 const $fetch = useRequestFetch() 获取带请求上下文的 $fetch,并同样不带响应泛型。内部应用间请求不要从 ofetch 导入 $fetch。
原因:带类型的 handler 为响应结构提供唯一事实来源,调用处泛型可能与真实载荷漂移且编译期无提示;useRequestFetch() 会在 SSR 期间把当前请求上下文(含 headers 与 cookies)转发到应用自身路由,而 ofetch 的普通 $fetch 不携带该上下文,受保护内部路由可能丢失会话状态。
示例: const { data } = await useFetch('/api/profile') const $fetch = useRequestFetch() await $fetch('/api/profile', { method: 'PATCH', body: { displayName: 'Ada' } })
export default defineEventHandler(async () : Promise<ProfileResponse> => { return { displayName: 'Ada' } })
边界:上述约定仅适用于应用自身内部路由。外部 HTTP 目标不参与 Nuxt 路由推断,也不需要 useRequestFetch() 向应用自身 API 转发 cookie;对外部目标应使用适合集成的客户端,必要时在调用处标注响应类型,例如从 ofetch 导入 $fetch 并使用泛型。
限制:资料未提供安装命令、版本要求、收费或价格信息。