用途
本技能用于客户端（浏览器端）的 Clerk 集成，覆盖 React 及其他前端框架。主要工作包括：选择正确的框架 SDK、接入 Provider 上下文、在预构建 UI 与自定义流程之间做选择、处理不同环境的跳转，以及避免把客户端认证状态误当作服务端授权。
SDK 选择
当存在专用框架 SDK 时优先使用：
| 应用类型 | 首选包/模式 |
|---|---|
| Next.js | @clerk/nextjs |
| 无更强集成的 React 应用 | @clerk/react |
| React Router 框架 | Clerk React Router SDK/模式 |
| TanStack React Start | Clerk TanStack 集成 |
| Astro | Clerk Astro 集成 |
| Nuxt/Vue | Clerk Nuxt/Vue 集成 |
| Expo/移动端 | Clerk Expo/移动端集成 |
| 纯 JavaScript/非 React | ClerkJS |
选错 SDK 会导致路由、SSR、水合（hydration）和令牌传递方面的缺陷。在新增包之前，先检查已安装的包。
Provider 与环境设置
在应用根部附近接入前端 Provider。Provider 应接收 publishable key，或使用框架 SDK 的环境变量约定。切勿把 secret key、webhook 签名密钥或 Backend API 凭据传给浏览器代码。
有意识地使用开发与生产 Clerk 实例。认证缺陷常源于把开发 publishable key 与生产域名、生产重定向 URL、生产 Backend API 密钥或生产 webhook 混用。
Provider 级选项和环境变量必须与 Clerk Dashboard 中的 URL 保持一致：
- 登录路由/路径。
- 注册路由/路径。
- 登录后与注册后的回退/强制重定向。
- 允许的来源/域名。
- 生产 OAuth 提供方的重定向与回调设置。
- 使用时的自定义域名/代理设置。
预构建组件与自定义流程
标准认证 UX 优先使用 Clerk 预构建组件：
- 登录与注册页面或弹窗。
- 用户按钮与账户管理。
- 用户资料与组织资料。
- 组织切换器与组织列表流程。
- 所选 UI 支持时的多会话账户切换。
当产品需要定制界面、渐进式引导、内嵌验证或自定义路由时，使用自定义流程。自定义流程应使用专门的登录/注册 hook，并显式处理中间状态。不要假设一次提交调用就能完成所有流程；验证步骤、MFA、passkey、SSO、邮箱验证码、手机验证码、OAuth 以及待处理会话任务都可能引入状态转换。
Hook 选择
按用途选择 hook：
| 需求 | Hook |
|---|---|
| 当前用户对象与加载状态 | useUser() |
| 认证状态、用户 ID、会话 ID、令牌获取 | useAuth() |
| 打开弹窗、登出、客户端方法 | useClerk() |
| 自定义登录流程 | useSignIn() |
| 自定义注册流程 | useSignUp() |
| 活动会话详情 | useSession() |
| 多会话 | useSessionList() |
| 活动组织 | useOrganization() |
| 组织列表/切换/创建 | useOrganizationList() |
始终处理加载与不可用状态。许多前端缺陷是空引用缺陷，原因是在 Clerk 加载完成前读取 user、session 或 organization。
跨源 API 调用
在受支持的框架集成中，同源请求通常可依赖 Clerk 管理的 cookie。跨源请求需要以 Bearer 令牌发送会话令牌。
客户端代码模式：
const { getToken } = useAuth()
const token = await getToken()
const res = await fetch('https://api.example.com/resource', {
headers: {
Authorization: `Bearer ${token}`,
},
})
if (!res.ok) {
throw new Error(`Request failed: ${res.status}`)
}
使用 ClerkJS 的纯 JavaScript 场景，概念上使用活动会话：
const token = await Clerk.session.getToken()
与代码相关的注意事项：
- getToken() 返回 Promise，必须 await。
- fetch() 对非 2xx 响应不会抛错，需检查 res.ok。
- 不要记录令牌，也不要存入 localStorage/sessionStorage。
- 不要把令牌放进 URL。
- 不要把令牌发送给不需要它的来源。
- 不要在浏览器中用客户端令牌执行特权 Backend API 操作。
- 确保后端 CORS 策略允许前端来源和 Authorization 头。
CORS、Cookie 与同源假设
对于同源的应用/API 路由，Clerk 管理的 cookie 通常会自动提供会话令牌。对于独立的 API 来源，除非架构和 cookie 设置明确支持，浏览器不会自动向该 API 发送可用的 Clerk 会话。跨源 API 优先使用 Bearer 令牌授权。
跨源请求失败时：
- 确认请求包含 Origin 和 Authorization。
- 确认 API 返回的 Access-Control-Allow-Origin 精确匹配前端来源；使用凭据时不能为 *。
- 确认 Access-Control-Allow-Headers 包含 Authorization 和 Content-Type。
- 确认任何 CDN 或 API 网关转发 Authorization。
- 确认前端与后端使用同一 Clerk 实例/环境。
路由与重定向
在 SDK、环境变量、路由和 Clerk Dashboard 中一致配置登录与注册 URL。实现受保护的客户端路由时，客户端检查仅用于 UX；访问控制也必须在服务端/API 强制执行。
对于 SPA，用感知加载状态的逻辑守卫路由渲染：
- 加载中：显示骨架屏/加载指示器，而非受保护数据。
- 已登出：重定向或渲染登录 UI。
- 已登录但无活动组织：若路由需要组织，显示组织选择。
- 已登录但未授权：显示不含敏感信息的拒绝访问 UI，并确保 API 也返回拒绝。
避免在认证状态未知前渲染受保护内容造成闪烁。对于 SSR 框架，优先使用可用的服务端或中间件保护。
组织与多会话 UX
启用组织功能时，需为活动组织选择做设计。UI 可能处于已登录但无活动组织的状态。组织切换会改变同一路由的授权，因此应在活动组织确定后再获取组织范围数据，并在组织变化时取消/重新获取过期请求。
对于允许多会话的应用，有意识地使用会话列表 API。让活动会话切换可见，并测试登出单个会话与登出全部会话的行为。
自定义登录/注册流程护栏
自定义流程应：
- 把登录/注册建模为状态机，而非一次表单提交。
- 处理验证策略、MFA、passkey、SSO 重定向、第一因素与第二因素要求以及待处理会话。
- 密码或 OTP 值的存储时间不超过当前请求。
- 优雅处理限流和机器人/滥用响应。
- 不要为简化 UI 而绕过 Clerk 推荐的验证步骤。
- 仅重定向到允许列表中的返回 URL；不要制造开放重定向。
前端安全边界
把前端 Clerk 状态视为展示状态。任何读取私有数据、修改数据、更改计费、更改角色、更改组织成员身份或执行管理工作的操作，都需要服务端授权。
不要仅把敏感授权逻辑放在隐藏按钮、禁用 UI 或客户端路由守卫中。用户可以直接调用 API。
不要暴露：
- CLERK_SECRET_KEY 或等价的 Backend API 密钥。
- Webhook 签名密钥。
- M2M 凭据或 API 密钥管理密钥。
- 仅服务端的 clerkClient 操作。
- 不应让用户看到的私有元数据。
开发与预览环境
使用环境特定的 publishable key 和重定向 URL。预览部署常有不同主机名；确认它们被正确的 Clerk 实例允许，且不会误用生产密钥。生产 OAuth 应配置提供方自有凭据，而非依赖开发/共享 Clerk 凭据。
排查清单
- 确认应用使用框架专用的 Clerk SDK。
- 确认 Provider 放置位置包裹了所有调用 Clerk hook 的组件。
- 确认 publishable key 与允许域名匹配环境。
- 读取 user/session/org 对象前检查加载状态。
- 跨源调用时检查请求是否含 Authorization: Bearer <token>。
- 确认 CORS 允许来源和 Authorization 头。
- 确认客户端重定向与路由、环境变量和 Clerk Dashboard 设置一致。
- 确认组织范围视图在活动组织变化时重新获取。
- 确认生产 OAuth 提供方和重定向 URL 已在提供方与 Clerk Dashboard 中配置。
- 确认 CSP 允许所选组件所需的 Clerk 脚本、frame、连接、图片和样式。