clerk-astro-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Astro Patterns

Astro模式

SDK:

@clerk/astro

v3+. Requires Astro 4.15+.

SDK:

@clerk/astro

v3+。要求Astro版本不低于4.15。

What Do You Need?

你需要什么？

Task	Reference
Configure middleware	references/middleware.md
Protect SSR pages	references/ssr-pages.md
Use Clerk in island components	references/island-components.md
Auth in API routes	references/api-routes.md
Use Clerk with React in Astro	references/astro-react.md

任务	参考文档
配置中间件	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

Mental Model

心智模型

Astro has two rendering modes per page: SSR and static prerender. Clerk works differently in each:

SSR pages — use
```
Astro.locals.auth()
```
which is populated by the middleware
Static pages (
```
export const prerender = true
```
) — Clerk middleware skips them; use client-side hooks in islands
Islands — React/Vue/Svelte components; use
```
useAuth()
```
and other hooks from
```
@clerk/astro/react
```

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

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()钩子

Setup

环境配置

astro.config.mjs

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

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

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()
})

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 Page Auth

SSR页面鉴权

astro

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

<h1>Dashboard</h1>

astro

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

<h1>Dashboard</h1>

Common Pitfalls

常见问题

Symptom	Cause	Fix
`Astro.locals.auth` is undefined	Missing middleware	Add `clerkMiddleware` to `src/middleware.ts`
Auth works in dev but not production	`output: 'static'` globally	Set `output: 'server'` or `hybrid` for protected pages
Static page has no auth	Prerendered pages skip middleware	Use `export const prerender = false` or move to island
Island not reactive to sign-in	Missing `client:load` directive	Add `client:load` to the island component

现象	原因	解决方法
`Astro.locals.auth` 未定义	缺少中间件配置	在 `src/middleware.ts` 中添加 `clerkMiddleware`
鉴权在开发环境正常但生产环境失效	全局配置了 `output: 'static'`	将受保护页面的 `output` 设置为 `server` 或 `hybrid`
静态页面无鉴权能力	预渲染页面会跳过中间件处理	设置 `export const prerender = false` 或将鉴权逻辑移到孤岛组件中
孤岛组件无法响应登录状态变化	缺少 `client:load` 指令	给孤岛组件添加 `client:load` 属性

Import Map

导入映射

What	Import From
`clerkMiddleware` , `createRouteMatcher`	`@clerk/astro/server`
`useAuth` , `useUser` , `UserButton`	`@clerk/astro/react`
Astro components ( `<SignIn>` , etc.)	`@clerk/astro/components`

内容	导入来源
`clerkMiddleware` , `createRouteMatcher`	`@clerk/astro/server`
`useAuth` , `useUser` , `UserButton`	`@clerk/astro/react`
Astro组件（ `<SignIn>` 等）	`@clerk/astro/components`

Env Variables

环境变量

undefined

undefined

.env

PUBLIC_CLERK_PUBLISHABLE_KEY=pk_... CLERK_SECRET_KEY=sk_...


Astro uses `PUBLIC_` prefix for client-exposed variables (not `NEXT_PUBLIC_`).

PUBLIC_CLERK_PUBLISHABLE_KEY=pk_... CLERK_SECRET_KEY=sk_...


Astro对客户端暴露的变量使用`PUBLIC_`前缀（而非`NEXT_PUBLIC_`）。

Docs

官方文档

Astro SDK

clerk-astro-patterns

Original

Translation

Astro Patterns

Astro模式

What Do You Need?

你需要什么？

Mental Model

心智模型

Setup

环境配置

astro.config.mjs

astro.config.mjs

src/middleware.ts

src/middleware.ts

SSR Page Auth

SSR页面鉴权

Common Pitfalls

常见问题

Import Map

导入映射

Env Variables

环境变量

.env

.env

See Also

相关参考

Docs

官方文档