clerk-astro-patterns

Astro 模式

SDK：@clerk/astro v4+。需要 Astro 5+。

你需要做什么？

任务	参考
配置中间件（基础 clerkMiddleware()、按页面进行检查）	references/middleware.md
保护 SSR 页面	references/ssr-pages.md
在岛屿组件中使用 Clerk	references/island-components.md
在 API 路由中进行身份验证	references/api-routes.md
在 Astro 中将 Clerk 与 React 搭配使用	references/astro-react.md

心智模型

Astro 的每个页面有两种渲染模式：SSR 和 静态预渲染。Clerk 在两种模式下的工作方式不同：

• SSR 页面 — 使用由中间件填充的 Astro.locals.auth()
• 静态页面（export const prerender = true）— Clerk 中间件会跳过这些页面；请在岛屿中使用客户端钩子
• 岛屿 — React/Vue/Svelte 组件；使用 @clerk/astro/react 中的 useAuth() 和其他钩子

Request → clerkMiddleware() → SSR page → Astro.locals.auth()
                                ↓
                         Island (.client) → useAuth() hook

设置

astro.config.mjs

import { defineConfig } from 'astro/config'
import clerk from '@clerk/astro'

export default defineConfig({
  integrations: [clerk()],
  output: 'server',
})

src/middleware.ts

import { clerkMiddleware } from '@clerk/astro/server'

export const onRequest = clerkMiddleware()

中间件会填充 Astro.locals.auth()。每个页面和 API 路由分别进行检查。createRouteMatcher 已在 @clerk/astro 4.0 中移除（在 3.x 中已弃用）。不要添加它。升级前，必须将现有用法改为页面和 API 路由检查。请参阅 Astro clerkMiddleware() 参考。

SSR 页面身份验证

---
const { userId, orgId } = Astro.locals.auth()
if (!userId) return Astro.redirect('/sign-in')
---

<h1>Dashboard</h1>

API 路由身份验证

// src/pages/api/data.ts
import type { APIRoute } from 'astro'

export const GET: APIRoute = ({ locals }) => {
  const { userId } = locals.auth()
  if (!userId) return new Response('Unauthorized', { status: 401 })

  return Response.json({ userId })
}

常见问题

症状	原因	修复方法
Astro.locals.auth 未定义	缺少中间件	将 clerkMiddleware 添加到 src/middleware.ts
身份验证在开发环境中有效，但在生产环境中无效	全局设置了 output: 'static'	为受保护页面设置 output: 'server' 或 hybrid
静态页面没有身份验证	预渲染页面会跳过中间件	使用 export const prerender = false，或将其移到岛屿中
岛屿无法响应登录状态变化	缺少 client:load 指令	将 client:load 添加到岛屿组件

导入映射

内容	导入自
clerkMiddleware、clerkClient	@clerk/astro/server
useAuth、UserButton（没有 useUser）	@clerk/astro/react
$userStore、$authStore	@clerk/astro/client
Astro 组件（<SignIn> 等）	@clerk/astro/components

环境变量

# .env
PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
CLERK_SECRET_KEY=sk_...

Astro 使用 PUBLIC_ 前缀来公开客户端变量（而不是 NEXT_PUBLIC_）。

另请参阅

• clerk-setup - Clerk 初始安装
• clerk-custom-ui - 自定义流程和外观
• clerk-orgs - B2B 组织

文档

Astro SDK