如何在Nuxt 3中扩展H3Event上下文类型？

要在不破坏defineEventHandler类型推断的前提下扩展event.context的类型，你需要遵循以下正确的类型声明方式：

1. 放置类型文件的正确位置 #

将类型声明文件放在项目根目录的types文件夹下（比如命名为types/context.d.ts），Nuxt会自动扫描该目录下的类型文件，无需额外配置。

2. 正确的类型扩展代码 #

// types/context.d.ts
import type { H3EventContext } from 'h3'

// 先定义你的AuthSession类型（如果是外部类型，直接导入即可）
type AuthSession = {
  user: number
  // 可添加其他业务需要的字段
}

declare module 'h3' {
  // 合并原有H3EventContext类型，添加auth字段
  interface H3EventContext {
    auth: AuthSession
  }
}

// 导出空对象，将文件标记为模块，避免全局类型冲突
export {}

3. 关键注意事项 #

• 必须添加export {}：这会让TypeScript将该文件识别为模块，而非全局类型声明，避免覆盖h3原有类型定义，导致event参数变为any。
• 确保AuthSession类型已定义：如果AuthSession来自其他文件，直接通过import type导入即可，比如import type { AuthSession } from '~/types/auth'。

验证生效效果 #

在服务器中间件或API路由中使用defineEventHandler时，event.context.auth会自动获得正确的类型提示，同时event的其他属性（如event.req、event.res等）仍保持原有类型：

// server/middleware/auth.ts
export default defineEventHandler((event) => {
  // 此处event.context.auth有明确的AuthSession类型，而非any
  event.context.auth = { user: 123 }
})

内容的提问来源于stack exchange，提问作者Evan Summers