Clerk Authentication 是一个用于在应用中集成 Clerk 身份认证的技能，资料标注状态为 Production Ready，最后更新于 2025-10-28，依赖为 None。资料列出的最新版本包括 @clerk/nextjs@6.33.3、@clerk/backend@2.17.2、@clerk/clerk-react@5.51.0、@clerk/testing@1.4.4。
用途与适用框架 该技能面向需要在 React/Vite、Next.js App Router 和 Cloudflare Workers 应用中接入 Clerk 认证的开发者。资料按框架分别给出快速开始步骤，整体定位为约 10 分钟可完成的基础集成指引。
React (Vite) 主要能力与使用方式 安装命令为 npm install @clerk/clerk-react。需要在 src/main.tsx 中配置 ClerkProvider，并确保其包裹整个应用。环境变量使用 VITE_ 前缀，例如 VITE_CLERK_PUBLISHABLE_KEY=pk_test_...，资料强调只有 VITE_ 前缀的变量会暴露给客户端代码。认证能力通过 hooks 提供：useUser() 返回 isLoaded、isSignedIn、user；useAuth() 返回 userId、sessionId、getToken；useClerk() 返回 openSignIn、signOut 等。资料强调渲染依赖认证状态的 UI 前必须先检查 isLoaded，以避免错误内容闪现。
Next.js App Router 主要能力与使用方式 安装命令为 npm install @clerk/nextjs。环境变量包括 NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY、CLERK_SECRET_KEY，以及可选的登录/注册及跳转 URL 配置。资料强调 CLERK_SECRET_KEY 绝不能暴露给客户端，客户端变量只能使用 NEXT_PUBLIC_ 前缀。路由保护通过项目根目录的 middleware.ts 实现，使用 clerkMiddleware 与 createRouteMatcher 定义公开路由，其余路由调用 await auth.protect() 保护。资料指出 v6 中 auth.protect() 为异步，是相对 v5 的破坏性变更。应用需在 app/layout.tsx 中用 ClerkProvider 包裹。服务端组件使用 @clerk/nextjs/server 的 auth() 与 currentUser()，其中 auth() 在 v6 中为异步，需 await；auth() 用于轻量检查，currentUser() 用于获取完整用户对象。
Cloudflare Workers 主要能力与使用方式 安装命令为 npm install @clerk/backend hono，资料列出的版本为 @clerk/backend@2.17.2 与 hono@4.10.1。本地开发使用 .dev.vars 配置 CLERK_SECRET_KEY 与 CLERK_PUBLISHABLE_KEY，生产环境使用 wrangler secret put CLERK_SECRET_KEY。令牌验证通过 @clerk/backend 的 verifyToken 实现，从 Authorization 头提取 Bearer token，并调用 verifyToken(token, { secretKey, authorizedParties })。资料强调必须设置 authorizedParties 以防止 CSRF 攻击，并使用 secretKey 而非已弃用的 apiKey。
JWT 模板与自定义声明 Clerk 允许通过模板自定义 JWT 结构，用于第三方服务集成、基于角色的访问控制和多租户应用。创建方式为在 Clerk Dashboard 的 Sessions 页面点击 Customize session token，再点击 Create template。模板支持短代码，如 {{user.id}}、{{user.primary_email_address}}、{{user.public_metadata.role || 'user'}} 等，涵盖用户 ID 与姓名、联系方式、资料、验证状态、元数据、组织信息等类别。资料还说明支持字符串插值、条件回退和点号嵌套元数据。每个 JWT 自动包含 azp、exp、iat、iss、jti、nbf、sub 等默认声明且不可覆盖。自定义声明存在 1.2KB 大小限制，原因是浏览器 cookie 限制为 4KB，而 Clerk 默认声明约占 2.8KB。资料提示在 Vite 开发模式测试自定义声明时可能遇到 431 Request Header Fields Too Large 错误，原因是 Clerk 握手令牌超出 Vite 的 8KB 限制。建议将大数据存数据库，JWT 中只放标识符和角色。TypeScript 类型安全可通过 types/globals.d.ts 声明 CustomJwtSessionClaims 实现。常见用例包括基于角色的访问控制、多租户应用和 Supabase 集成。
测试能力 资料提供测试凭据：测试邮箱如 john+clerk_test@example.com、jane+clerk_test@gmail.com，测试电话如 +12015550100、+19735550133，固定 OTP 为 424242。可通过脚本生成会话令牌，命令示例为 CLERK_SECRET_KEY=sk_test_... node scripts/generate-session-token.js，支持 --create-user 与 --refresh 参数。手动流程为创建用户、创建会话、生成令牌，再以 Authorization: Bearer <token> 使用。E2E 测试可安装 @clerk/testing，在 Playwright 中通过 clerkSetup() 与 setupClerkTestingToken() 使用。Testing Tokens 可绕过机器人检测，通过 POST https://api.clerk.com/v1/testing_tokens 获取。资料说明 Testing Tokens 在生产环境也可用，但基于代码的认证（短信/邮件 OTP）在生产环境不支持，邮箱加密码认证和魔法链接受支持。
已知问题预防 该技能汇总了 11 个已知问题，包括缺少 Clerk Secret Key、apiKey 到 secretKey 的迁移、JWKS 缓存竞态条件、缺少 authorizedParties 导致 CSRF、Core 2 导入路径变更、JWT 大小超限、API v1 弃用、ClerkProvider JSX 组件错误、异步 auth() 助手混淆等，并分别给出预防措施。
限制与暂未提供 资料未提供收费、价格、平台支持范围、性能效果等具体信息。部分内容（如 Issue #9 的说明）在资料中未完整呈现。