---
title: "@vonvon-kit/nuxt"
description: "带 H3/Nitro 服务端 middleware 和自动导入 Vue composable 的 Nuxt 3 模块，适用于 SSR 和全栈应用。"
locale: "zh-Hans"
---

> Documentation Index
> Fetch the relevant documentation index at: https://vonvon.id/zh-hans/sdks/llms.txt
> Use this file to discover all available pages before exploring further.

# @vonvon-kit/nuxt

## 状态

Registry 状态:UNPUBLISHED。此 SDK 只能从仓库源码 checkout 安装；不要使用外部 package registry。

包状态为 **当前包**。Nuxt 模块、H3/Nitro 服务端 middleware 和自动导入 composable 已实现。在真实生产基础设施上的 IdP 往返验证仍待人工核实。

## 模块配置

将 `@vonvon-kit/nuxt` 添加到 `modules` 数组。该模块自动导入所有 [@vonvon-kit/vue](/zh-hans/sdks/vue) composable，并注册安装 `VonvonPlugin` 的仅客户端插件。

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@vonvon-kit/nuxt'],
  vonvon: {
browser: {
  mode: 'oidc',
  issuer: 'https://vonvon.id',
  clientId: 'client_abc123',
  redirectUri: 'https://app.example.com/auth/callback',
},
  },
})
```

## Composable（自动导入）

```vue
<script setup lang="ts">
// No import needed -- Nuxt auto-imports from @vonvon-kit/vue
const auth = useAuth()
const userRef = useUser()
const orgRef = useOrganization()
const sessionRef = useSession()
</script>

<template>
  <div v-if="auth.isSignedIn">
Signed in as {{ auth.userId }}
<button @click="auth.signOut()">Sign out</button>
  </div>
</template>
```

## 服务端 middleware（JWT 认证）

`createVonvonServerMiddleware` 返回一个 H3 handler，用于验证 Bearer 或显式应用 JWT，并写入 `event.context.vonvonAuth`。通过 `sessionTokenExchange` 配置同源 Core session；H3 v1 相对 URL 还需要可信的 `requestOrigin`。将文件放入 `server/middleware/`，使 Nitro 将其注册为全局 middleware。

```ts
// server/middleware/vonvon.ts
import { createVonvonServerMiddleware } from '@vonvon-kit/nuxt'

export default createVonvonServerMiddleware({
  jwtKey: JSON.parse(process.env.VONVON_JWKS_PUBLIC_KEY!),
  issuer: 'https://acme.vonvon.id',
  sessionTokenExchange: { endpoint: '/v1/sessions/token' },
  requestOrigin: process.env.VONVON_APP_ORIGIN!,
  protectedRoutes: ['/api/admin'],
})
```

## 在服务端路由中读取认证信息

```ts
// server/routes/api/me.get.ts
import { getVonvonAuth } from '@vonvon-kit/nuxt'

export default defineEventHandler((event) => {
  const auth = getVonvonAuth(event)
  if (!auth.userId) {
throw createError({ statusCode: 401, message: 'Unauthorized' })
  }
  return { userId: auth.userId, orgId: auth.orgId }
})
```

## 导出的 API

| 导出 | 类型 | 用途 |
| --- | --- | --- |
| `createVonvonServerMiddleware` | function | H3 事件处理器工厂：验证 JWT，写入 event.context.vonvonAuth，保护路由 |
| `getVonvonAuth` | function | 在服务端路由和处理器中从 event.context.vonvonAuth 读取 AuthResult |
| `VONVON_AUTH_CONTEXT_KEY` | 字符串常量 | 用于存储认证结果的上下文 key（'vonvonAuth'） |
| `VonvonServerMiddlewareOptions` | type | jwtKey, issuer, authorizedParties, jwtCookieName, sessionTokenExchange, requestOrigin, protectedRoutes, onUnauthenticated |

## 安全注意事项

- `event.context.vonvonAuth` 仅限服务端使用，不会发送到浏览器。
- middleware 会剥离客户端提供的任何认证 token，并重新注入已验证的结果。
- 将 middleware 文件放在 `server/middleware/` 中，以确保它作为全局 Nitro middleware 覆盖所有路由。

Source: https://vonvon.id/zh-hans/sdks/nuxt/index.mdx