用途
本技能定位为 Clerk 现代身份认证专家，用于在应用中实现现代认证与良好用户体验，主要覆盖 WebAuthn、通行密钥（passkeys）、无密码流程、预置 UI 组件以及多租户组织支持。适用于需要使用现代认证方式的开发场景。
主要能力
- WebAuthn 与通行密钥（passkeys）
- 无密码（passwordless）认证流程
- 预置的认证 UI 组件
- 多租户组织（organization）支持
- 路由保护、服务端认证、组织切换等实现模式
SDK 版本与运行要求
资料给出的 SDK 版本（截至 2025 年 12 月）：
- @clerk/nextjs 6.x（Core 2），要求 Next.js 13.0.4 或更高版本，React 18 或更高版本
- @clerk/clerk-react 5.x（Core 2），要求 React 18 或更高版本
- @clerk/express 1.x
- 要求 Node.js 18.17.0 或更高版本
使用方式
环境变量
.env.local 文件需要设置：NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY（可发布密钥，以 pk_test 开头）、CLERK_SECRET_KEY（密钥，以 sk_test 开头）、NEXT_PUBLIC_CLERK_SIGN_IN_URL（登录路由路径）、NEXT_PUBLIC_CLERK_SIGN_UP_URL（注册路由路径）。
ClerkProvider 设置
在 app/layout.tsx 中从 @clerk/nextjs 导入 ClerkProvider，RootLayout 组件用 ClerkProvider 包裹 html 与 body 元素，children 通过 body 传入。
基础中间件
在 middleware.ts 中从 @clerk/nextjs/server 导入 clerkMiddleware，默认导出 clerkMiddleware 调用，并导出 config 对象，其 matcher 数组包含除静态文件与 Next.js 内部路径外的所有路由模式，以及 api 与 trpc 路由模式。
Context7 访问
库：/clerk/clerk-docs；先用 resolve-library-id 查询 "clerk"，再使用 get-library-docs。
实现指南要点
- 带认证组件的 ClerkProvider：在布局中导入 ClerkProvider、SignInButton、SignUpButton、SignedIn、SignedOut、UserButton；用 SignedOut 包裹显示登录/注册按钮，用 SignedIn 包裹显示 UserButton。
- 使用中间件保护路由：使用 createRouteMatcher 定义 isProtectedRoute（如 /dashboard、/forum、/api/private 等模式），匹配受保护路由时调用 auth.protect()；也可定义 isPublicRoute，对所有非公开路由调用 auth.protect()。
- useAuth 钩子：解构 userId、sessionId、getToken、isLoaded、isSignedIn；getToken 获取会话令牌用于携带 Authorization Bearer 头的 API 调用；渲染前检查 isLoaded，展示认证内容前检查 isSignedIn。
- useUser 钩子：解构 isSignedIn、user、isLoaded；访问 firstName、primaryEmailAddress.emailAddress、imageUrl 等属性。
- 登录与注册页面：创建
app/sign-in/[[...sign-in]]/page.tsx与app/sign-up/[[...sign-up]]/page.tsx，分别渲染 SignIn 与 SignUp 组件，使用 flexbox 居中布局。 - 服务端认证：App Router 服务端组件中导入 auth、currentUser 与 redirect；await auth() 获取 userId，为 null 时重定向到登录；await currentUser() 获取完整用户对象。路由处理器中 await auth()，userId 为 null 时返回 401。
- 组织管理：OrganizationSwitcher 组件用于组织切换；useOrganizationList 钩子可自定义切换（userMemberships 设为 infinite 模式，遍历 userMemberships.data 显示组织名与 select 按钮，调用 setActive 传入组织 ID，hasNextPage 为真时提供加载更多按钮）；useOrganization 钩子获取当前组织，展示 name、imageUrl、membersCount。
高级模式与 Core 2 迁移
更多高级模式（Core 2 迁移、基于角色的访问控制、webhooks、自定义认证流程、外部服务集成）见 modules/advanced-patterns.md。
Core 2 主要迁移变更：
- 环境变量：CLERK_FRONTEND_API 改为 NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
- 中间件：authMiddleware() 改为 clerkMiddleware()
- 导入：服务端由 @clerk/nextjs 改为 @clerk/nextjs/server
- 会话：setSession() 改为 setActive()
- 图片：profileImageUrl 与 logoUrl 改为 imageUrl
迁移工具命令：npx @clerk/upgrade --from=core-1，从 Core 1 迁移到 Core 2。
适用场景与限制
该技能面向使用 Clerk 进行现代认证与多租户组织管理的开发场景，官方文档、SDK 参考与迁移指南等资源链接已在资料中给出。资料标注状态为 Production Ready，版本 2.1.0，最后更新 2026-01-11，SDK 版本 @clerk/nextjs 6.x（Core 2）。关于收费、价格或未在资料中提及的功能与效果，暂未提供。