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 密钥认证(自定义中间件足够)
- 预算限制无法使用托管服务
详细资源:
- reference.md - 决策框架、钩子快速参考、Core 3 迁移速查表
- examples/core.md - ClerkProvider、环境变量、中间件配置
- examples/components.md - 预构建组件、自定义、外观属性
- examples/hooks.md - useUser、useAuth、useSession、加载状态、条件渲染
- examples/server.md - 服务端组件、API 路由、服务端操作、Webhook 处理
- examples/organizations.md - 组织管理、角色、权限、RBAC
理念
Clerk 是一个托管认证平台,处理完整的认证生命周期:注册、登录、会话管理、用户资料、组织和 MFA。无需从头构建认证,你可以集成 Clerk 的 SDK 和预构建组件。
核心原则:
- 纵深防御——在中间件层保护路由,并在每个数据访问点验证认证。仅靠中间件是不够的(CVE-2025-29927 演示了中间件绕过漏洞)。
- 服务端优先认证——在服务端组件和路由处理器中使用
auth()和currentUser()。仅在需要反应式客户端状态时才使用客户端钩子(useUser、useAuth)。 - 预构建优于自定义——使用 Clerk 的
<SignIn>、<SignUp>、<UserButton>组件。仅当预构建组件确实无法满足需求时才构建自定义流程。 - 组织用于多租户——为 B2B 应用使用带有角色和权限的 Clerk 组织。不要在 Clerk 的用户模型之上构建自定义租户系统。
- 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>