integrating-clerk-expo

Expo（React Native）中的 Clerk 身份验证

关键限制（请先阅读）

• Expo 原生应用不支持 Clerk 邮件链接。请优先使用邮件验证码（email_code）或其他策略。
• Expo 原生应用不支持 Clerk 预构建 UI 组件。请使用自定义流程（自行创建界面）和控制组件： <ClerkLoaded>、<ClerkLoading>、<SignedIn>、<SignedOut>、<Protect>。
• 默认会话令牌存储在内存中；对于原生应用，几乎总是应该使用安全令牌缓存（Expo SecureStore）。

此技能的作用

在 Expo 应用中实现 Clerk 时，请遵循以下工作流：

• 安装并配置 @clerk/clerk-expo 和环境密钥
• 使用安全的 tokenCache 将应用封装在 <ClerkProvider> 中
• 构建自定义登录/注册界面（电子邮件 + 密码、邮件验证码）
• 在 Expo Router 或 React Navigation 中保护路由/界面
• 通过 useSSO() 添加 OAuth / 企业 SSO 流程（并解决重定向/深层链接问题）
• 通过 useSignInWithApple() 添加原生 通过 Apple 登录（iOS，原生构建）
• 通过 useLocalCredentials() 添加可选的生物识别重新验证
• 可选启用实验性的离线引导功能 __experimental_resourceCache
• 为生产部署做好准备（域名 + 允许列表中的重定向 URL）

快速检查清单（默认：Expo Router）

复制/粘贴并逐项勾选：

• 在 Clerk Dashboard 中为应用启用 Native API。
• 安装：@clerk/clerk-expo
• 添加 .env：EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=...
• 使用 <ClerkProvider tokenCache={tokenCache}> 封装根组件
• 安装 SecureStore 并使用 Clerk 的 tokenCache 辅助工具
• 创建 (auth) 路由组，其中包含 sign-in.tsx、sign-up.tsx 和 (auth)/_layout.tsx 重定向守卫
• 使用 useClerk().signOut() 添加登出按钮
• 使用 <SignedIn> / <SignedOut> / <Protect> 或 useAuth() + 重定向保护已登录内容
• 如果使用 OAuth/SSO：实现 useSSO() + expo-auth-session 重定向 URL + WebBrowser.maybeCompleteAuthSession()
• 如果需要 iOS Apple 登录：使用原生构建 + useSignInWithApple()
• 如果需要离线弹性：使用 __experimental_resourceCache={resourceCache} 并处理 network_error
• 生产环境：获取域名，并将移动 SSO 重定向 URL 添加到允许列表

如需完整代码示例，请打开：

• references/QUICKSTART.md
• references/CUSTOM_FLOWS.md
• references/SSO_OAUTH.md
• references/HOOKS_AND_COMPONENTS.md

---

确定路由配置

如果项目使用 Expo Router

特征：

• 依赖项中包含 expo-router
• 有一个 app/ 目录，其中包含 app/_layout.tsx 之类的路由文件

➡️ 请遵循：下文的 Expo Router 工作流。

如果项目直接使用 React Navigation（不使用 Expo Router）

特征：

• App.tsx 中包含 NavigationContainer 和导航栈
• 没有 app/ 目录

➡️ 请遵循：下文的 React Navigation 工作流。

---

工作流 A — Expo Router（推荐默认配置）

1) 安装 + 环境密钥

• 安装 @clerk/clerk-expo
• 在 .env 中设置 EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY

2) 根布局：ClerkProvider + 安全令牌缓存

在 app/_layout.tsx（或项目的根布局）中封装应用：

import { ClerkProvider } from '@clerk/clerk-expo'
import { tokenCache } from '@clerk/clerk-expo/token-cache'
import { Slot } from 'expo-router'

export default function RootLayout() {
  return (
    <ClerkProvider tokenCache={tokenCache}>
      <Slot />
    </ClerkProvider>
  )
}

注意：

• 确保已安装 expo-secure-store（tokenCache 辅助工具所必需）。
• 客户端中只保留可发布密钥。

3) 身份验证路由组 + 重定向守卫

创建 app/(auth)/_layout.tsx，将已登录用户重定向离开身份验证界面：

import { Redirect, Stack } from 'expo-router'
import { useAuth } from '@clerk/clerk-expo'

export default function AuthLayout() {
  const { isSignedIn } = useAuth()
  if (isSignedIn) return <Redirect href="/" />
  return <Stack />
}

4) 构建自定义登录/注册界面

使用 Clerk 钩子（useSignIn、useSignUp），并优先采用 email_code 验证。

参见：

• references/CUSTOM_FLOWS.md

5）保护已登录路由

选项（任选其一，不要随意混用）：

• 声明式：使用 <SignedIn> 和 <SignedOut> 包裹已登录区域。
• 保护子树：在需要身份验证的内容外使用 <Protect>。
• 命令式：在布局中检查 useAuth()，并使用 <Redirect> 重定向到 /sign-in。

请参阅：

• references/ROUTING.md

---

工作流 B — React Navigation（不使用 Expo Router）

1）包裹根节点

使用 <ClerkProvider tokenCache={tokenCache}> 包裹你的 NavigationContainer（或应用根节点）。

2）根据身份验证状态拆分导航

• 当 !isLoaded 时：渲染启动／加载屏幕
• 当 isSignedIn 时：渲染“应用”导航栈
• 否则：渲染“身份验证”导航栈

请参阅：

• references/ROUTING.md

---

Expo 中的 OAuth／企业 SSO（useSSO）

使用 useSSO() 进行 OAuth 和企业 SSO。在原生环境中，你必须提供有效的重定向 URL（通常通过 AuthSession.makeRedirectUri(...) 提供），并确保生产环境中已将你的重定向 URL 加入允许列表。

请参阅：

• references/SSO_OAUTH.md
• references/DEPLOYMENT.md

---

使用 Apple 登录（iOS 原生构建）

useSignInWithApple() 仅适用于 iOS，且需要原生构建（无法在 Expo Go 中运行）。 始终处理 ERR_REQUEST_CANCELED。

请参阅：

• references/APPLE_SIGNIN.md

---

生物识别（存储本地凭据）

useLocalCredentials() 可在设备上存储密码凭据，以便之后通过生物识别登录（Face ID／指纹）。仅适用于基于密码的登录尝试。

请参阅：

• references/BIOMETRICS.md

通行密钥

Clerk 支持通行密钥（WebAuthn）。在 Expo 应用中，你需要通过自定义工作流集成通行密钥；请参阅 Clerk 的通行密钥参考文档，了解最新支持的策略和平台限制。

请参阅：

• references/PASSKEYS.md

---

离线支持（实验性）

你可以通过 __experimental_resourceCache 启用实验性的离线引导。请将其视为实验性功能；针对 network_error 添加完善的错误处理。

请参阅：

• references/OFFLINE_SUPPORT.md

---

验证流程（推荐）

1）运行设置验证器：

python scripts/verify_expo_clerk_setup.py .

2）清除缓存后启动 Expo：

npx expo start -c

3）测试以下流程：

• 全新安装 → 注册 → 验证代码 → 应用屏幕
• 重启应用 → 用户仍保持登录状态（令牌缓存正常工作）
• 退出登录 → 用户返回身份验证导航栈（令牌已清除）

---

精确提示词 — 在 Expo 应用中实现 Clerk

将此内容用于委派给其他编码 Agent：

You are implementing Clerk authentication in a React Native Expo app.

1) Detect whether this app uses Expo Router (app/ directory) or React Navigation.
2) Install and configure @clerk/clerk-expo with EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY.
3) Wrap the root with <ClerkProvider tokenCache={tokenCache}> and ensure expo-secure-store is installed.
4) Implement custom sign-in and sign-up screens (email + password, with email verification code strategy 'email_code').
5) Protect signed-in routes appropriately for the chosen router.
6) If OAuth/SSO is requested, implement useSSO() with expo-auth-session redirectUrl and WebBrowser.maybeCompleteAuthSession().
7) Add sign-out.
8) Provide a short test plan and run scripts/verify_expo_clerk_setup.py.

Be precise and keep changes minimal. Do not use email link flows on native.

---

快速搜索（阅读打包的参考文档时）

grep -Rni "useSSO" references/
grep -Rni "tokenCache" references/
grep -Rni "enterprise_sso" references/
grep -Rni "__experimental_resourceCache" references/