Astro 模式
SDK:@clerk/astro v3+。需要 Astro 4.15+。
你需要什么?
| 任务 | 参考 |
|---|---|
| 配置中间件 | references/middleware.md |
| 保护 SSR 页面 | references/ssr-pages.md |
| 在岛屿组件中使用 Clerk | references/island-components.md |
| API 路由中的身份验证 | references/api-routes.md |
| 在 Astro 中结合 React 使用 Clerk | references/astro-react.md |
心智模型
Astro 为每个页面提供两种渲染模式:SSR 和 静态预渲染。Clerk 在每种模式下的工作方式不同:
- SSR 页面 —— 使用由中间件填充的
Astro.locals.auth() - 静态页面(
export const prerender = true)—— Clerk 中间件会跳过它们;请使用岛屿中的客户端钩子 - 岛屿 —— React/Vue/Svelte 组件;使用
@clerk/astro/react中的useAuth()和其他钩子
请求 → clerkMiddleware() → SSR 页面 → Astro.locals.auth()
↓
岛屿 (.client) → useAuth() 钩子
设置
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, createRouteMatcher } from '@clerk/astro/server'
const isProtectedRoute = createRouteMatcher(['/dashboard(.*)'])
export const onRequest = clerkMiddleware((auth, context, next) => {
if (isProtectedRoute(context.request) && !auth().userId) {
return auth().redirectToSignIn()
}
return next()
})
SSR 页面身份验证
---
const { userId, orgId } = Astro.locals.auth()
if (!userId) return Astro.redirect('/sign-in')
---
<h1>仪表盘</h1>
常见陷阱
| 症状 | 原因 | 修复 |
|---|---|---|
Astro.locals.auth 未定义 | 缺少中间件 | 在 src/middleware.ts 中添加 clerkMiddleware |
| 开发环境正常但生产环境身份验证失效 | 全局使用了 output: 'static' | 为受保护页面设置 output: 'server' 或 hybrid |
| 静态页面无身份验证 | 预渲染页面会跳过中间件 | 使用 export const prerender = false 或移至岛屿组件 |
| 岛屿组件对登录无反应 | 缺少 client:load 指令 | 为岛屿组件添加 client:load |
导入映射
| 内容 | 导入来源 |
|---|---|
clerkMiddleware、createRouteMatcher | @clerk/astro/server |
useAuth、useUser、UserButton | @clerk/astro/react |
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 组织