---
title: "@xid-kit/astro"
description: "适用于静态和服务端渲染 Astro 站点的 Astro 集成，包含 SSR middleware、服务端辅助工具和 island 客户端单例。"
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/astro

## 状态

包状态为 **当前包**。Astro 集成、SSR middleware、服务端辅助工具和 island 客户端单例已实现。在真实生产基础设施上的 IdP 往返验证仍待人工核实。

## 集成配置

在 `astro.config.mjs` 中注册 `xidIntegration`。该集成通过 `addMiddleware` 以 `pre` 顺序注入认证 middleware，并向客户端 island 提供 publishable key。

```js
// astro.config.mjs
import { defineConfig } from 'astro/config'
import { xidIntegration } from '@xid-kit/astro'
import node from '@astrojs/node'

export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
  integrations: [
xidIntegration({
  publishableKey: import.meta.env.PUBLIC_XID_PK,
  jwtKey: import.meta.env.XID_JWT_KEY,
  protectedRoutes: ['/dashboard', '/account'],
  signInUrl: '/sign-in',
}),
  ],
})
```

## 手动 middleware（替代方案）

```ts
// src/middleware.ts
import { sequence } from 'astro:middleware'
import { createXidMiddleware } from '@xid-kit/astro'

export const onRequest = sequence(
  createXidMiddleware({
jwtKey: import.meta.env.XID_JWT_KEY,
issuer: 'https://xid.dev',
protectedRoutes: ['/dashboard', '/account'],
signInUrl: '/sign-in',
  }),
)
```

## .astro 页面中的服务端认证

```astro
---
// src/pages/dashboard.astro
import { getAuth, currentUser } from '@xid-kit/astro/server'

const auth = getAuth(Astro.locals)
if (!auth.userId) return Astro.redirect('/sign-in')

const user = await currentUser(Astro.locals, {
  secretKey: import.meta.env.XID_SECRET_KEY,
})
---

<h1>Welcome, {user?.primaryEmailAddress}</h1>
```

## 客户端 island

```tsx
// src/components/SignOutButton.tsx
import { getClient } from '@xid-kit/astro/client'

export default function SignOutButton() {
  const client = getClient()

  const handleSignOut = async () => {
await client.signOut()
window.location.href = '/'
  }

  return <button onClick={handleSignOut}>Sign out</button>
}
```

## Astro.locals 类型定义

将类型引用添加到 `src/env.d.ts`，以获得 `Astro.locals.xidAuth` 的完整类型覆盖。

```ts
/// <reference path="../node_modules/@xid-kit/astro/src/locals.d.ts" />
```

## 导出的 API

| 导出 | 类型 | 模块 |
| --- | --- | --- |
| `xidIntegration` | Astro 集成工厂 | `@xid-kit/astro` |
| `createXidMiddleware` | middleware 工厂 | `@xid-kit/astro` |
| `getAuth, currentUser, xidClient` | 服务端辅助工具 | `@xid-kit/astro/server` |
| `getClient, initClient, resetClient` | island 客户端单例 | `@xid-kit/astro/client` |

## 安全注意事项

- `jwtKey` 是 JWKS 公钥；可安全用于 networkless 验证，不包含私钥。
- `secretKey`（`sk_live_xxx`）必须仅限服务端使用；不要传给 island 或客户端 bundle。
- 受保护路由在任何页面处理器运行前通过 middleware 中的 `Response.redirect` 重定向；无需客户端 JS。
- 重导出 [@xid-kit/backend](/zh-hans/sdks/backend) 的 `authenticateRequest` 用于 networkless JWT 验证路径。

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