clerk-auth

用途：面向使用 Clerk 认证的开发者，汇总破坏性变更、关键模式与常见错误预防，减少升级与集成中的踩坑。

主要能力：

1. API 2025-11-10 破坏性变更：/commerce/ 改为 /billing/（30+ 端点），payment_source 改为 payment_method，移除 amount、currency、payer_type 等字段及 invoices、products 端点，null 语义明确化。
2. Next.js v6 异步 auth()：const { userId } = await auth()，中间件中 await auth.protect()，支持 Next.js 15/16。
3. 自定义 OAuth 的 PKCE 支持，适用于无法安全存储密钥的移动/原生应用。
4. Client Trust 凭据填充防御，对无 2FA 用户在新设备登录时自动二次验证，无需配置。
5. JWT 模板：自定义声明上限 1.2KB，提供短代码参考与最小化声明建议。
6. 测试：固定 OTP 424242，测试邮箱与电话，@clerk/testing 配合 Playwright，生成会话令牌脚本。

必要用法：Cloudflare Workers 中 verifyToken 必须设置 authorizedParties 防 CSRF；Vite 开发模式遇 431 错误可在 package.json 中设置 NODE_OPTIONS='--max-http-header-size=32768'。

适用场景：Clerk 升级迁移、Next.js 服务端组件鉴权、JWT 模板设计、端到端测试。

限制：资料未提供具体收费与价格信息；部分内容依赖官方文档链接，需自行查阅。