用途
该技能定位为 Clerk 现代认证专家，覆盖 WebAuthn、通行密钥（passkeys）、无密码（passwordless）流程、预构建的精美 UI 组件以及多租户组织支持。适用于在实现现代认证且追求良好用户体验时使用。
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：完整布局从 @clerk/nextjs 导入 ClerkProvider、SignInButton、SignUpButton、SignedIn、SignedOut 和 UserButton。RootLayout 用 ClerkProvider 包裹全部内容。header 元素中，SignedOut 包裹在未认证时显示的 SignInButton 与 SignUpButton，SignedIn 包裹在已认证时显示的 UserButton。children 在 header 下方的 body 中渲染。
用中间件保护路由：使用 createRouteMatcher 进行路由保护时，从 @clerk/nextjs/server 导入 clerkMiddleware 和 createRouteMatcher。用 createRouteMatcher 定义 isProtectedRoute，传入受保护路由模式数组（如 /dashboard、/forum 以及带通配后缀的 /api/private 路径）。middleware 函数检查请求是否匹配受保护路由，若匹配则调用 auth.protect()。导出带 matcher 数组的 config 对象。若要保护除公开路由外的所有路由，则用 createRouteMatcher 定义 isPublicRoute，包含 sign-in、sign-up、根路径和 about 等公开路径，middleware 对任何非公开路由调用 auth.protect()。
useAuth 钩子：在客户端组件中从 @clerk/nextjs 导入 useAuth，解构 userId、sessionId、getToken、isLoaded 和 isSignedIn。getToken 函数用于获取会话令牌，供 API 调用携带 Authorization Bearer 头。渲染前检查 isLoaded，展示已认证内容前检查 isSignedIn。
useUser 钩子：在客户端组件中从 @clerk/nextjs 导入 useUser，解构 isSignedIn、user 和 isLoaded。访问 user 属性包括 firstName、primaryEmailAdddess.emailAdddess 和 imageUrl 以展示个人资料。
SignIn 与 SignUp 页面：创建 app/sign-in/[[...sign-in]]/page.tsx 并从 @clerk/nextjs 导入 SignIn，SignInPage 组件使用 flexbox 与 min-h-screen、items-center justify-center 类将 SignIn 组件居中渲染。同样创建 app/sign-up/[[...sign-up]]/page.tsx 并导入 SignUp，SignUpPage 以相同居中布局渲染 SignUp 组件。
服务端认证：对于 App Router 服务端组件，从 @clerk/nextjs/server 导入 auth 与 currentUser，从 next/navigation 导入 redirect。在 async DashboardPage 组件中 await auth() 获取 userId，若为 null 则重定向到登录；await currentUser() 获取完整用户对象用于展示。对于 Route Handler 认证，从 @clerk/nextjs/server 导入 auth，从 next/server 导入 NextResponse。在 GET handler 中 await auth() 获取 userId，若为 null 返回 401 Unauthorized，否则在响应中返回 userId。
组织管理：OrganizationSwitcher 组件从 @clerk/nextjs 导入并在仪表盘布局中渲染，提供下拉菜单供用户切换所属组织。自定义组织切换时使用 useOrganizationList 钩子，将 userMemberships 配置为 infinite 模式，渲染前检查 isLoaded，遍历 userMemberships.data 展示组织名称与调用 setActive 的选择按钮（传入组织 ID），当 hasNextPage 为 true 时显示加载更多按钮。useOrganization 钩子提供当前组织信息，解构 organization 与 isLoaded，选定组织后展示其 name、imageUrl 和 membersCount。
适用场景
适用于在 Next.js、React 与 Express 项目中实现现代认证：包括通行密钥与无密码登录、预构建 UI 组件、服务端与客户端认证状态管理、受保护路由、组织与多租户切换，以及从 Core 1 迁移到 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。迁移工具：运行 Clerk 升级命令 npx @clerk/upgrade 并指定 --from=core-1，从 Core 1 迁移到 Core 2。
资源
官方文档：Next.js 快速开始见 clerk.com/docs/quickstarts/nextjs；SDK 参考见 clerk.com/docs/reference/nextjs/overview；Core 2 迁移见 clerk.com/docs/guides/development/upgrading/upgrade-guides/core-2/nextjs；Webhooks 见 clerk.com/docs/integrations/webhooks。
可配合使用：moai-platform-auth0（替代企业 SSO 方案）、moai-platform-supabase（Supabase 认证集成）、moai-platform-vercel（Vercel 部署搭配 Clerk）、moai-lang-typescript（TypeScript 开发模式）、moai-domain-frontend（React 与 Next.js 集成）。
状态：Production Ready；版本：2.1.0；最后更新：2026-01-11；SDK 版本：@clerk/nextjs 6.x（Core 2）。