Clerk 身份认证

要解决的问题

在 Next.js 14/15 App Router 中接入 Clerk 时，容易把认证上下文、环境变量、登录组件和路由保护散落在页面组件里，导致 会话判断不一致 和 受保护路由遗漏。本技能把 Clerk 认证收敛为一套可复用的 App Router 模式，减少手工拼装 ClerkProvider、auth() 和中间件时常见的配置偏差。

技能如何工作

它围绕三个关键点组织：

• 应用上下文：用 ClerkProvider 包裹应用，配置环境变量，并提供基本的登录/注册组件。
• 路由保护：在根目录维护单个 middleware.ts，使用 clerkMiddleware 和 createRouteMatcher 做路由分组，并通过 auth.protect() 显式保护敏感路径。
• 服务器组件认证：在 Server Component 中调用 auth() 获取 userId、sessionId、orgId、claims，调用 currentUser() 获取完整用户对象。

关键边界是：服务器组件中的认证函数依赖 Clerk 中间件提供的请求上下文，因此中间件不能只是可选增强，而应作为认证逻辑的集中入口。

适用边界

该技能适合使用 Next.js App Router 和 Clerk 的项目，重点覆盖认证设置与受保护路由。它不替代业务权限模型，也不会为页面组件、数据库权限或第三方身份源做额外抽象。资料中的潜在问题表为占位内容，具体严重度和解决方案需结合 Clerk 文档确认。