Communitygithub.com

Clerk 认证模式

Clerk 管理的认证 - ClerkProvider、中间件、预构建组件、钩子、服务端认证、组织、Webhooks

Clerk 认证模式 是什么?

此技能文档提供了在 Next.js 应用中使用 Clerk 管理认证平台的完整指南。Clerk 处理完整的认证生命周期,包括注册、登录、会话管理、用户资料、组织和 MFA。该技能涵盖了核心模式,例如使用 `clerkMiddleware()` 进行路由保护(在生产环境中使用 `proxy.ts` 或 `middleware.ts` 以及显式的公共路由白名单),使用新的 `<Show>` 组件进行条件渲染(它取代了 Core 3 中已弃用的 `<SignedIn>`/`<SignedOut>`/`<Protect>`),以及使用 `useUser()` 和 `useAuth()` 等客户端钩子实现反应式状态管理。它强制采用“深度防御”方法,要求在中间件层和数据访问层都进行验证,并强调使用 `verifyWebhook` 进行 Webhook 签名验证。该技能还涵盖了使用组织实现多租户、使用 `auth()` 和 `currentUser()` 实现服务端认证(并强调切勿将 `privateMetadata` 传递给客户端),以及在 Core 3 中从 `@clerk/shared/types` 进行类型导入。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/agents-inc/skills/tree/HEAD/src/skills/api-auth-clerk

在你喜欢的 AI 中提问

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

文档

Clerk 认证模式 是做什么的?

快速指南: Clerk 提供托管式认证,包含预构建的 UI 组件、服务端助手以及基于组织的多租户支持。使用 clerkMiddleware() 进行路由保护,使用 <Show> 进行条件渲染,使用钩子管理客户端状态,使用 auth()/currentUser() 进行服务端认证。Clerk Core 3(2026 年)使用 <Show> 取代 <SignedIn>/<SignedOut>,将中间件文件重命名为 proxy.ts(Next.js 16+),并整合了包。


<critical_requirements>

关键:使用本技能前须知

所有代码必须遵循 CLAUDE.md 中的项目约定(kebab-case、命名导出、导入排序、import type、命名常量)

(你必须使用 @clerk/nextjs/server 进行所有服务端导入——切勿从 @clerk/nextjs 导入服务端助手)

(你必须使用 Clerk 的 verifyWebhook 助手验证 Webhook——切勿信任未经验证的 Webhook 载荷)

(你必须使用 <Show> 组件替代已弃用的 <SignedIn>/<SignedOut>/<Protect>——这些已在 Core 3 中移除)

(你绝不能将完整的 currentUser() 对象传递给客户端——它包含必须保留在服务端的 privateMetadata)

(你必须在中间件和数据访问层都保护路由——仅靠中间件是不够的)

</critical_requirements>


自动检测: Clerk、ClerkProvider、clerkMiddleware、@clerk/nextjs、useUser、useAuth、useClerk、useSession、useOrganization、SignIn、SignUp、UserButton、UserProfile、OrganizationSwitcher、auth()、currentUser()、CLERK_SECRET_KEY、NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY、Show when="signed-in"

何时使用:

  • 为应用添加认证和用户管理
  • 构建使用基于组织的访问控制的多租户 B2B 应用
  • 使用支持可定制主题的预构建登录/注册 UI 组件
  • 使用中间件和服务端授权检查保护路由
  • 通过 Webhooks 将 Clerk 用户数据同步到数据库

涵盖的关键模式:

  • ClerkProvider 设置、环境变量、中间件配置
  • 预构建 UI 组件(<SignIn>、<SignUp>、<UserButton>、<Show>)
  • 客户端钩子(useUser、useAuth、useSession、useOrganization)
  • 在服务端组件、路由处理器、服务端操作中的服务端认证(auth()、currentUser())
  • 使用 clerkMiddleware() 和 createRouteMatcher() 的中间件路由保护
  • 基于组织的多租户,支持角色和权限
  • 使用 Svix 签名验证的 Webhook 处理

何时不使用:

  • 需要自托管认证(需要完全控制认证数据存储)
  • 无法使用第三方认证服务(合规/监管限制)
  • 简单的 API 密钥认证(自定义中间件足够)
  • 预算限制无法使用托管服务

详细资源:


理念

Clerk 是一个托管认证平台,处理完整的认证生命周期:注册、登录、会话管理、用户资料、组织和 MFA。无需从头构建认证,你可以集成 Clerk 的 SDK 和预构建组件。

核心原则:

  1. 纵深防御——在中间件层保护路由,并在每个数据访问点验证认证。仅靠中间件是不够的(CVE-2025-29927 演示了中间件绕过漏洞)。
  2. 服务端优先认证——在服务端组件和路由处理器中使用 auth() 和 currentUser()。仅在需要反应式客户端状态时才使用客户端钩子(useUser、useAuth)。
  3. 预构建优于自定义——使用 Clerk 的 <SignIn>、<SignUp>、<UserButton> 组件。仅当预构建组件确实无法满足需求时才构建自定义流程。
  4. 组织用于多租户——为 B2B 应用使用带有角色和权限的 Clerk 组织。不要在 Clerk 的用户模型之上构建自定义租户系统。
  5. Webhook 驱动的同步——通过 Webhook(而非轮询)将 Clerk 数据同步到数据库。始终使用 verifyWebhook 验证 Webhook 签名。

何时使用 Clerk:

  • 你需要快速实现认证,且自定义代码最少
  • 你想要用于登录/注册/用户管理的预构建 UI 组件
  • 你需要基于组织的多租户和 RBAC
  • 你想要托管的 MFA、SSO(SAML/OIDC)和社交登录

何时不使用 Clerk:

  • 你需要完全控制认证数据存储(自托管要求)
  • 你无法使用第三方认证服务(合规/监管)
  • 你的应用只需要简单的 API 密钥认证
  • 预算限制无法使用托管服务

核心模式

模式 1:ClerkProvider 和中间件设置

每个 Clerk 应用都需要用 <ClerkProvider> 包装应用,并用 clerkMiddleware() 保护路由。完整设置示例见 examples/core.md。

关键规则:

  • ClerkProvider 放在 <body> 内部,而不是包裹 <html>——Core 3 要求如此
  • 使用 NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY 环境变量,切勿硬编码密钥
  • 在 Next.js 16+ 上中间件文件是 proxy.ts,在 Next.js <=15 上是 middleware.ts
  • Webhook 端点必须在公共路由列表中(由 verifyWebhook 单独验证)
  • Webhook 签名的环境变量是 CLERK_WEBHOOK_SIGNING_SECRET(不是 CLERK_WEBHOOK_SECRET)
// proxy.ts (Next.js 16+) 或 middleware.ts (Next.js <=15)
const isPublicRoute = createRouteMatcher([
  "/",
  "/sign-in(.*)",
  "/sign-up(.*)",
  "/api/webhooks(.*)",
]);

export default clerkMiddleware(async (auth, req) => {
  if (!isPublicRoute(req)) {
    await auth.protect();
  }
});

为什么好: 公共路由被显式列入白名单,其他所有内容都需要认证,Webhook 端点是公开的(单独验证)

// 错误:不带回调的 clerkMiddleware()
export default clerkMiddleware(); // 默认所有路由都是公开的!

为什么不好: 不带回调的 clerkMiddleware() 会附加认证数据,但不会保护任何路由


模式 2:预构建 UI 组件和 <Show>

使用 <Show> 进行条件渲染(Core 3 中替代 <SignedIn>/<SignedOut>/<Protect>)。完整示例见 examples/components.md。

<Show when="signed-out"><SignInButton /></Show>
<Show when="signed-in"><UserButton /></Show>
<Show when={{ role: "org:admin" }}><AdminPanel /></Show>
<Show when={(has) => has({ permission: "org:invoices:manage" })}><InvoiceManager /></Show>

为什么好: <Show> 是 Core 3 API,支持字符串/对象/回调条件,fallback 属性用于未授权

// 错误:已弃用——在 Core 3 中已移除
<SignedIn>...</SignedIn>
<SignedOut>...</SignedOut>
<Protect role="admin">...</Protect>

为什么不好: <SignedIn>、<SignedOut>、<Protect> 在 Core 3 中已移除,请使用带有 when 属性的 <Show>

登录/注册页面需要通配路由段 [[...sign-in]] 以支持多步骤流程(MFA、OAuth 回调)。


模式 3:客户端钩子

在客户端组件中使用钩子实现反应式认证状态。在访问数据前务必检查 isLoaded。 完整示例见 examples/hooks.md。

"use client";
const { isLoaded, isSignedIn, user } = useUser();
if (!isLoaded) return <div>加载中...</div>;
if (!isSignedIn) return <div>请登录</div>;
// 现在可以安全访问 user.firstName、user.emailAddresses 等

为什么好: 防止在初始化期间因访问 undefined 导致的 hydration 错误,防止在未登录时因访问 null 导致的 TypeError

// 错误:未加守卫就访问 user
const { user } = useUser();
return <p>{user.firstName}</p>; // 当 isLoaded=false 或 isSignedIn=false 时运行时错误

为什么不好: 在加载完成前 user 是 undefined,未登录时是 null

关键钩子:

  • useUser() —— 用户资料数据(姓名、邮箱、头像)
  • useAuth() —— 会话令牌(getToken())、userId、orgId、用于授权的 has()
  • useOrganization() —— 活跃组织数据、成员资格、分页成员列表
  • useReverification() —— 在敏感操作前重新认证(Core 3)

在 Core 3 中,离线时 getToken() 会抛出 ClerkOfflineError 而不是返回 null——务必用 try/catch 包裹。


模式 4:服务端认证

从 @clerk/nextjs/server 使用 auth() 和 currentUser()。完整示例见 examples/server.md。

auth() —— 轻量级,无 API 调用,读取会话声明:

import { auth } from "@clerk/nextjs/server";
const { userId, orgId, isAuthenticated, redirectToSignIn } = await auth();
if (!isAuthenticated) return redirectToSignIn();

currentUser() —— 完整的用户对象,进行后端 API 调用:

import { currentUser } from "@clerk/nextjs/server";
const user = await currentUser();
// 关键:在传递给客户端组件之前选取安全字段
const safeData = { firstName: user.firstName, imageUrl: user.imageUrl };

为什么关键: currentUser() 返回的 privateMetadata 绝不能到达客户端。显式选取字段。

纵深防御: 必须在每个服务端操作和路由处理器中检查认证,而不仅仅是中间件:

"use server";
const { userId } = await auth();
if (!userId) throw new Error("未授权");
// userId 将所有查询/变更限定为当前用户

模式 5:使用角色和权限的授权

使用 auth.protect() 或 has() 实现细粒度访问控制。RBAC 模式见 examples/organizations.md。

// 中间件:基于角色的路由保护
await auth.protect((has) => has({ role: "org:admin" }));

// 服务端组件:权限检查
const { has } = await auth();
if (!has({ permission: "org:invoices:delete" })) redirect("/dashboard");

// 客户端:按角色条件渲染
<Show when={{ role: "org:admin" }}><AdminPanel /></Show>

权限格式: org:<feature>:<action>(例如 org:invoices:create、org:reports:read)

默认角色: org:admin(所有权限)、org:member(只读)。自定义角色在 Clerk 仪表板中配置。


模式 6:Webhook 处理

使用 Clerk Webhooks(通过 Svix)将用户数据同步到数据库。完整处理器见 examples/server.md。

import { verifyWebhook } from "@clerk/nextjs/webhooks";

export async function POST(req: Request) {
  const evt = await verifyWebhook(req); // 读取 CLERK_WEBHOOK_SIGNING_SECRET 环境变量
  // evt.type: "user.created" | "user.updated" | "user.deleted" | "organization.*" | ...
  // evt.data: UserJSON | OrganizationJSON | 等等
}

为什么好: verifyWebhook 验证 Svix 签名,始终返回 200 以防止重试,Webhook 路由在中间件中是公开的(由签名而非认证验证)

// 错误:无签名验证
const body = await req.json(); // 任何人都可以 POST 虚假数据!
await db.insert(users).values(body.data); // 安全漏洞

为什么不好: 没有签名验证意味着任何人都可以向你的端点发送虚假的 Webhook 事件

从 @clerk/shared/types(Core 3)导入类型: UserJSON、OrganizationJSON、OrganizationMembershipJSON


<decision_framework>

决策框架

客户端与服务端认证

你在哪里需要认证数据?
|-- 服务端组件、路由处理器、服务端操作
|   |-- 仅需要 userId/sessionId?--> auth()
|   |-- 需要完整的用户对象?--> currentUser()
|   |-- 需要保护路由?--> auth.protect()
|   +-- 需要组织上下文?--> auth() 返回 orgId、orgRole
|
+-- 客户端组件(交互式 UI)
    |-- 需要用户资料数据?--> useUser()
    |-- 需要会话/令牌数据?--> useAuth()
    |-- 需要组织数据?--> useOrganization()
    +-- 需要底层 Clerk API?--> useClerk()

路由保护策略

这是什么类型的路由?
|-- 公开(落地页、登录、注册、Webhooks)
|   +-- 添加到 isPublicRoute 匹配器,跳过 auth.protect()
|
|-- 需认证(仪表板、个人资料、设置)
|   +-- 中间件中的 auth.protect() + 数据层中的 auth() 检查
|
+-- 需授权(管理、组织特定、权限门控)
    |-- 基于角色?--> auth.protect({ role: "org:admin" })
    +-- 基于权限?--> auth.protect((has) => has({ permission: "org:feature:action" }))

组件选择

你需要什么认证 UI?
|-- 完整登录页面 --> 通配路由上的 <SignIn />
|-- 完整注册页面 --> 通配路由上的 <SignUp />
|-- 登录按钮(模态框) --> <SignInButton />
|-- 用户头像 + 菜单 --> <UserButton />
|-- 完整资料编辑器 --> <UserProfile />
|-- 组织切换器 --> <OrganizationSwitcher />
+-- 条件内容 --> <Show when="signed-in"> 或 <Show when={{ role: "..." }}>

</decision_framework>


<red_flags>

红旗警告

高优先级问题:

  • 从 @clerk/nextjs 而非 @clerk/nextjs/server 导入服务端助手(在服务端组件中会出错)
  • 使用已弃用的 <SignedIn>/<SignedOut>/<Protect> 组件(在 Core 3 中已移除)
  • 将完整的 currentUser() 对象传递给客户端组件(泄漏 privateMetadata)
  • 未经 verifyWebhook 签名验证就信任 Webhook 载荷
  • 仅依赖中间件进行路由保护(中间件可被绕过)
  • 从 @clerk/types 而非 @clerk/shared/types 导入类型(Core 3 重新组织了包)

</red_flags>

Individual skills in this repo

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

相关技能