Communitygithub.com

deangilmoreremix/videoremix.vip2

Astro 模式集成 Clerk —— 中间件、SSR 页面、岛屿组件、API 路由、静态与 SSR 渲染。触发关键词:astro clerk、clerk astro middleware、astro protected page、clerk island component、astro API route auth、clerk astro SSR。

videoremix.vip2 是什么?

该技能为 Astro 项目(4.15+)提供了一套完整的 Clerk 身份验证集成模式。它涵盖了中间件配置、SSR 页面保护、岛屿组件中的用户状态管理以及 API 路由的身份验证。技能文档清晰地解释了 Astro 中 SSR 与静态预渲染两种模式的区别,以及 Clerk 如何在不同模式下工作:SSR 页面通过中间件填充的 `Astro.locals.auth()` 获取用户身份,而静态页面则需借助岛屿组件中的客户端钩子(如 `useAuth()`)。技能还提供了常见陷阱的排查表,例如中间件缺失、全局静态输出导致生产环境认证失败等问题的解决方案。支持的平台包括 Astro 项目,使用的 SDK 为 `@clerk/astro` v3+。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/deangilmoreremix/videoremix.vip2/tree/HEAD/.agents/skills/clerk-astro-patterns

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Astro 模式

SDK:@clerk/astro v3+。需要 Astro 4.15+。

你需要什么?

任务参考
配置中间件references/middleware.md
保护 SSR 页面references/ssr-pages.md
在岛屿组件中使用 Clerkreferences/island-components.md
API 路由中的身份验证references/api-routes.md
在 Astro 中结合 React 使用 Clerkreferences/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 组织

文档

Astro SDK

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

deangilmoreremix/videoremix.vip2

Implement Clerk authentication for native Android apps using Kotlin and Jetpack Compose with clerk-android source-guided patterns. Use for prebuilt AuthView/UserButton or custom API-driven auth flows. Do not use for Expo or React Native projects.

deangilmoreremix/videoremix.vip2

Clerk Backend REST API explorer and executor. Browse tags, inspect endpoint schemas, and execute authenticated requests. Use when listing users, managing organizations, or calling any Clerk API endpoint.

deangilmoreremix/videoremix.vip2

Clerk Billing for subscription management - render Clerk's PricingTable and in-app checkout drawer, configure subscription plans, seat-limit plans for B2B, feature entitlements with has(), and billing webhooks. Use for SaaS monetization, plan gating, checkout flows, trials, invoicing, and subscription lifecycle management.

deangilmoreremix/videoremix.vip2

Chrome Extension auth with @clerk/chrome-extension -- popup/sidepanel setup, syncHost for OAuth/SAML via web app, createClerkClient for service workers and headless extensions, stable CRX ID. Triggers on: Chrome extension auth, Plasmo clerk, popup sign-in, syncHost, background service worker token, createClerkClient, headless extension.

deangilmoreremix/videoremix.vip2

>- Operate the Clerk CLI (`clerk` binary) for authentication, user/org/session management, deploy verification, instance config, env keys, and any Clerk Backend or Platform API call. Use when the user mentions Clerk management tasks, "list clerk users", "create a clerk user", "update organization", "pull clerk config", "clerk env pull", "clerk doctor", "clerk deploy", "clerk deploy status", "clerk api", or any ad-hoc Clerk API request. Prefer the CLI over raw HTTP: it handles auth, key resolution, app/instance targeting, and formatting automatically.

deangilmoreremix/videoremix.vip2

Custom authentication flows and component appearance - hooks (useSignIn, useSignUp), themes, colors, fonts, CSS. Use for custom sign-in/sign-up flows, appearance styling, visual customization, branding.

deangilmoreremix/videoremix.vip2

Agent skill / project related to launch or product demo video: deangilmoreremix/videoremix.vip2

相关技能