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

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

# @xid-kit/nuxt

## 状态

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

## 模块配置

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

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@xid-kit/nuxt'],

  runtimeConfig: {
public: {
  xidApiUrl: '', // optional: omit for same-origin deployment
},
  },
})
```

## Composable（自动导入）

```vue
<script setup lang="ts">
// No import needed -- Nuxt auto-imports from @xid-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 认证）

`createXidServerMiddleware` 返回一个 H3 事件处理器，以 networkless 方式验证 JWT 并写入 `event.context.xidAuth`。将文件放在 `server/middleware/` 中，使 Nitro 将其注册为全局 middleware。

```ts
// server/middleware/xid.ts
import { createXidServerMiddleware } from '@xid-kit/nuxt'

export default createXidServerMiddleware({
  jwtKey: JSON.parse(process.env.XID_JWKS_PUBLIC_KEY!),
  issuer: 'https://acme.xid.dev',
  protectedRoutes: ['/api/admin'],
})
```

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

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

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

## 导出的 API

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

## 安全注意事项

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

Source: https://xid.dev/zh-hans/sdks/nuxt/index.mdx