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 中將 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, 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 組織