用途：整理 Clerk 认证集成中的破坏性变更与错误预防要点，帮助开发者避免升级与配置陷阱。
主要能力：汇总包版本（@clerk/nextjs@6.36.7、@clerk/backend@2.29.2、@clerk/clerk-react@5.59.2、@clerk/testing@1.13.26）；说明 API 版本 2025-11-10 变更（端点 /commerce/ 改 /billing/、字段 payment_source 改 payment_method、移除字段与端点、null 处理规则）；Next.js 16 中间件文件由 middleware.ts 改为 proxy.ts 及其安全背景；Next.js v6 中 auth() 需 await、auth.protect() 需 await；clerkMiddleware() 路由保护、选项与组织同步；Webhook 用 svix 验证签名且路由须公开；JWT 模板自定义声明上限约 1.2KB 及可用短代码；测试凭据固定 OTP 424242、@clerk/testing 与 Playwright 集成；以及 15 个常见问题的预防。
使用方式：按资料示例配置环境变量与代码。Cloudflare Workers 场景调用 verifyToken 时必须设置 authorizedParties 以防 CSRF；JWT 模板自定义声明控制在 1.2KB 以内；Vite 开发模式出现 431 时可调整 NODE_OPTIONS='--max-http-header-size=32768'。测试可用 CLERK_SECRET_KEY=sk_test_... node scripts/generate-session-token.js 生成会话令牌。
适用场景：Next.js 15/16、Cloudflare Workers、Express 等运行时中的 Clerk 认证接入、升级与排错。
限制：组织同步仅适用于 Next.js 的 clerkMiddleware()，不适用于其他运行时的 authenticateRequest()；API Keys 处于 Beta，资料给出创建 $0.001/key、验证 $0.0001/verification 的价格，其他收费政策暂未提供。