clerk-expo

Clerk Expo（React Native）

在 Expo / React Native 项目中集成 Clerk。本技能内置了适用于稳定接口（提供方、令牌缓存、流程）的已验证模式；对于任何易变内容（组件属性、钩子签名），则要求检查已安装的 @clerk/expo 包源码。

激活规则

符合以下任一条件时激活：

• 用户要求在 Expo 或 React Native 应用中添加身份验证，或提及原生应用中的 @clerk/expo、ClerkProvider、Expo Router 身份验证或 Clerk 钩子。
• 项目使用 Expo/React Native（存在 app.json / app.config.js、package.json 中包含 expo、metro.config.js 或依赖 @clerk/expo）。

以下情况应转到其他技能：

• 原生 iOS/Swift 项目（.xcodeproj、Package.swift）→ clerk-swift
• 原生 Android/Kotlin 项目（不含 React Native 的 build.gradle）→ clerk-android
• 仅限 Web 的框架（Next.js、Remix、纯 React 等）→ 对应的框架技能

意图映射

根据用户的需求选择对应参考资料。只加载任务所需的参考资料。

用户意图（示例）	路径	参考资料
“为我的应用添加身份验证” / “使用 Clerk 添加登录”	预构建原生组件（默认）	references/setup.md + references/prebuilt-components.md
“添加身份验证”，但要求使用 Expo Go / Web / 自定义 UI	自定义流程	references/setup.md + references/custom-flows.md
“添加电话 / SMS 身份验证”、“电子邮件 OTP”、“无密码登录”	自定义流程，phoneCode / emailCode	references/custom-flows.md
“使用 Google/Apple/GitHub 登录”、“社交登录”、“SSO”	浏览器 SSO 或原生按钮	references/sso-and-native-auth.md
“MFA / 2FA / TOTP”、“忘记密码”、“电子邮件链接”	自定义流程扩展	references/custom-flows.md
“保护路由/屏幕”、“退出登录时重定向”	Expo Router 路由守卫	references/protected-routes.md
“显示用户资料”、“切换组织”、“推送通知”、“退出登录”、“调用我的后端”	应用方案	references/recipes.md
“生物识别登录”、“Face ID”、“通行密钥”	设备功能	references/recipes.md

默认路径决策

当用户只说“添加身份验证”，没有指定 UI 时：

1. 默认使用预构建原生组件（来自 @clerk/expo/native 的 AuthView + UserButton）。这是最快实现可用身份验证的方式；UI 由 Clerk 维护。请告知开发者，这些组件目前处于测试阶段，且需要开发构建。
2. 以下任一情况成立时，改用自定义流程，并说明切换原因：
   • 项目必须在 Expo Go 中运行（不能进行开发构建）。
   • 应用面向 Web（原生组件无法在 Web 上渲染）。
   • 开发者想要自己的 UI，或想通过主题定制之外的方式打造特定品牌体验。
3. 如果开发者已有身份验证 UI，则在现有基础上扩展；除非对方提出要求，否则不要删除自定义流程并换成 AuthView（反之亦然）。

同一身份验证步骤不要混用预构建组件和自定义流程（例如同时使用 AuthView 和自定义密码表单）。只有开发者明确提出要求时才允许混用。

快速工作流

1. 确认项目类型（Expo/RN），并根据意图映射 / 默认路径规则选择方案。
2. 按照 references/setup.md 操作：安装、环境密钥、提供方、令牌缓存、配置插件、构建类型。
3. 核实仪表板前置条件（下文的 Gate 2 和 Gate 3）。
4. 仅根据所选参考资料实现。
5. 通过构建验证，而不只是编写代码：
   • 运行项目的类型检查（npx tsc --noEmit 或等效命令）。
   • 构建并启动：原生功能使用 npx expo run:ios / run:android；Expo Go 流程使用 npx expo start。如果构建失败，请修复并迭代重建——当本技能与 SDK 不一致时，针对已安装 SDK 的构建错误才是最终依据。连续尝试修复约 5 次仍失败后，请停止并询问开发者如何继续，而不要反复折腾。
   • 引导开发者完成一次实际登录，然后确认应用重启后会话仍然有效（这表示令牌缓存正常工作）。

执行门槛（不可跳过）

1. 可发布密钥 — 从 process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY（.env 文件）读取。绝不可使用 NEXT_PUBLIC_，也绝不可硬编码。如果没有密钥，请向开发者索取（或运行 npx clerk@latest init --framework expo，该命令会安装 SDK 并写入环境文件），并等待对方提供后再编辑文件。
2. Native API 仪表板开关 — 必须为该实例启用 Clerk 的 Native API：Clerk Dashboard → Native applications (https://dashboard.clerk.com/~/native-applications)。设置期间请告知开发者确认此项；任何原生集成都需要启用它。
3. 验证因素是否可用 — 实现特定策略（SMS、邮件验证码、社交服务提供方）之前，确认该实例已启用相应因素。根据可发布密钥推导 Frontend API URL（对中间部分进行 base64 解码），并获取 <frontendApiUrl>/v1/environment?_is_native=true，或者请开发者检查仪表板（User & authentication）。尤其要注意，SMS 是否可用取决于实例配置——为已禁用的因素编写的代码会在运行时失败，而非构建时失败。
4. 仅使用当前 custom-flows API — @clerk/expo（v3.4+）中的 useSignIn() / useSignUp() 返回 { signIn, errors, fetchStatus }，并使用基于方法的流程：signIn.password()、signIn.phoneCode.sendCode()、signIn.finalize()。绝不可生成旧模式代码：从 useSignIn() / useSignUp() 解构 isLoaded / setActive（当前 Hook 不会返回这些值），或将 signIn.create() 与 prepareFirstFactor() / attemptFirstFactor() 链接后再调用 setActive({ session })。该模式位于 @clerk/expo/legacy，仅用于维护现有旧代码，绝不可用于新工作。适用范围说明：useAuth() / useUser() 返回的 isLoaded 属于当前 API，且在守卫中必不可少；signIn.create() 本身仍可用于高级场景——优先使用特定因素的方法。
5. 使用 useSSO()，绝不使用 useOAuth() — useOAuth 已弃用。请注意两者的差异：startSSOFlow() 仍会返回 { createdSessionId, setActive }，并且需要调用 setActive({ session: createdSessionId })——SSO 不使用 finalize()。
6. 令牌缓存 — 在 ClerkProvider 上使用来自 @clerk/expo/token-cache 的 tokenCache。绝不可直接使用 expo-secure-store 存储会话令牌，也绝不可使用 AsyncStorage。
7. 使用 resourceCache，绝不使用 secureStore — 如果涉及离线资源缓存，@clerk/expo/secure-store 已弃用；请改用来自 @clerk/expo/resource-cache 的 resourceCache。
8. 按构建类型控制 — 原生组件（@clerk/expo/native）和原生 Hook（useSignInWithGoogle、useSignInWithApple、useLocalCredentials）需要开发构建（npx expo run:ios / run:android），不能使用 Expo Go，且不适用于 Web。对于 Web 目标，请使用 @clerk/expo/web 组件或自定义流程。实现仅限原生的功能之前，先说明此构建要求。
9. 默认使用组合式登录或注册流程 — 使用一个组合流程，除非开发者要求分别提供登录和注册页面。
10. 机器人防护 — 自定义注册页面必须渲染 <View nativeID="clerk-captcha" />。Clerk 的机器人防护默认已启用，需要此挂载点。
11. 核验易变接口 — 使用原生组件属性或原生 Hook 选项之前，请对照已安装的软件包确认：node_modules/@clerk/expo/dist/native/*.d.ts 和 package.json 中的 exports。如果已安装版本与本指南不一致，以已安装版本为准。
12. 新鲜度门槛 — 本指南已针对 @clerk/expo 3.6.x 验证。检查已安装的版本（node_modules/@clerk/expo/package.json）。如果安装的是更新的小版本或大版本，请谨慎对待本指南中的代码片段：使用之前，需根据每个代码片段旁边引用的文档 URL（每个参考章节都附有一个）或已安装的 .d.ts 重新核验。如果版本低于 3.4，则可能不支持基于方法的 custom-flows API——请建议升级，而不是编写旧版代码。

版本说明（v3.5–v3.6，2026 年 6 月）

• v3.5.0 将最低 React Native 版本提升至 0.75（iOS SDK 现在通过 SPM podspec 链接）。兼容范围：expo >=53 <57。
• 原生组件已趋于成熟：iOS 已迁移至 Expo Modules；原生与 JS 之间的会话同步会自动双向进行——使用原生组件完成身份验证后，切勿调用 setActive()。
• 配置插件接受用于设置原生组件样式的 theme JSON 文件（参见 references/prebuilt-components.md）。
• 原生 Google 登录将在下一个主版本中迁移至独立的 @clerk/expo-google-signin 包（在 v3 中，@clerk/expo/google 导入仍然有效；开发环境警告会提示迁移）。请勿在 v3 中预先安装新包。

常见问题

级别	问题	预防措施
严重	生成旧式自定义流程代码（signIn.create + prepareFirstFactor + setActive）	使用当前基于方法的 API（关卡 4）
严重	使用 useOAuth()	使用 useSSO()（关卡 5）
严重	实现短信／社交身份验证前未检查相应验证因素是否已启用	先检查环境／控制面板（关卡 3）
严重	将原生组件用于 Expo Go 或 Web	要求使用开发构建；否则提供自定义流程（关卡 8）
严重	注册页面缺少 <View nativeID="clerk-captcha" />	始终包含此组件（关卡 10）
高	使用 NEXT_PUBLIC_ 环境变量前缀，或在 node_modules 中读取环境变量	使用 EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY，并显式传入 ClerkProvider
高	重启后会话丢失	在 Provider 上使用来自 @clerk/expo/token-cache 的 tokenCache
高	使用 AuthView／UserButton 完成身份验证后调用 setActive()	原生组件会自动同步会话
高	将 AuthView 与 useSignInWithGoogle／useSignInWithApple 搭配使用	AuthView 会自行渲染已启用的社交身份验证提供方
高	手动调用 WebBrowser.maybeCompleteAuthSession()	ClerkProvider 会处理此事
高	未经要求就拆分登录／注册流程	默认使用合并流程（关卡 9）
中	守卫中未先检查 isLoaded 就检查 isSignedIn	始终先以 isLoaded 作为判断条件
中	在本地开发 @clerk/expo 时使用 yalc／pnpm link	使用 Verdaccio 或 pkg.pr.new

另请参阅

• clerk — 顶层路由器
• clerk-swift／clerk-android — 原生移动 SDK
• clerk-orgs、clerk-billing、clerk-webhooks — 功能技能（在 Expo 中，钩子的工作方式相同）
• 已安装的软件包源代码：node_modules/@clerk/expo/
• https://clerk.com/docs/getting-started/quickstart（Expo SDK 选项卡）
• https://clerk.com/docs/reference/expo/overview
• https://github.com/clerk/clerk-expo-quickstart — 三个官方示例应用：仅 JS（Expo Go）、JS + 原生登录按钮、原生组件