SuperAPI AI 工具集

clerk-expo

编程与开发

查看项目

更新于 10-27 12:59

技能介绍

clerk-expo 是一个用于在 Expo 与 React Native 项目中实现 Clerk 身份认证的技能。它以 @clerk/expo 包为基础,内置了 provider 配置、token 缓存、认证流程等稳定部分的已验证模式,并要求对组件属性、hook 签名等易变接口以已安装包的源码为准。

【激活条件】当用户要求在 Expo 或 React Native 应用中添加认证,或提及 @clerk/expo、ClerkProvider、Expo Router 认证、原生应用中的 Clerk hooks 时激活;当项目检测到 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 登录默认走预构建原生组件(setup 与 prebuilt-components);需在 Expo Go、Web 或自定义 UI 时走自定义流程(setup 与 custom-flows);手机/SMS、邮箱验证码、无密码登录走 custom-flows 中的 phoneCode/emailCode;Google/Apple/GitHub 等社交登录与 SSO 走 ss o-and-native-auth;MFA/2FA/TOTP、忘记密码、邮件链接走 custom-flows;保护路由或未登录重定向走 Expo Router 守卫(protected-routes);用户资料、组织切换、推送通知、退出登录、调用后端走 recipes;生物识别、Face ID、通行密钥走 recipes。

【默认路径选择】用户未指定 UI 时默认使用预构建原生组件(来自 @clerk/expo/native 的 AuthView 与 UserButton),并告知开发者其处于 beta 阶段且需要 development build。若项目必须运行在 Expo Go、目标为 Web(原生组件不在 Web 渲染)或开发者需要自有品牌 UI 时,改为自定义流程并说明原因。若已有认证 UI,应在原有基础上扩展而非擅自替换。不得对同一认证步骤混用预构建组件与自定义流程,除非开发者明确要求。

【工作流程】确认项目类型并按意图选择路径;按 setup 参考完成安装、环境密钥、provider、token 缓存、配置插件与构建类型;核对仪表盘前置条件;仅依据选定参考实现;通过构建验证(运行类型检查,用 npx expo run:ios / run:android 构建原生特性,或用 npx expo start 运行 Expo Go 流程),构建失败需迭代修复,约 5 次失败后停止并询问开发者;引导完成一次真实登录,并确认会话在应用重启后仍保留。

【执行门禁】发布密钥须从 process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY 读取,不得使用 NEXT_PUBLIC_ 前缀或硬编码,缺失时需向开发者索取或运行 npx clerk@latest init --framework expo;须在 Clerk Dashboard 原生应用页启用 Native API;实现特定认证因子(SMS、邮箱验证码、社交提供方)前确认实例已启用,可从发布密钥推导 Frontend API URL 并请求环境接口或请开发者核对仪表盘;自定义流程仅使用 useSignIn()/useSignUp() 返回 { signIn, errors, fetchStatus } 的基于方法的现代 API(如 signIn.password()、signIn.phoneCode.sendCode()、signIn.finalize()),不得生成旧版 signIn.create() 链式模式(旧版位于 @clerk/expo/legacy,仅用于维护既有代码);使用 useSSO() 而非已弃用的 useOAuth(),注意 startSSOFlow() 仍返回 { createdSessionId, setActive } 且需手动 setActive;token 缓存须使用 @clerk/expo/token-cache 的 tokenCache,不得直接用 expo-secure-store 或 AsyncStorage;离线资源缓存使用 @clerk/expo/resource-cache,secure-store 已弃用;原生组件与原生 hooks 需要 development build 且不支持 Web;默认合并登录与注册为单一流程;自定义注册页必须渲染 <View nativeID="clerk-captcha" />;使用易变属性前核对 node_modules/@clerk/expo/dist/native/*.d.ts 与 package.json 导出;技能基于 @clerk/expo 3.6.x 验证,若安装版本更新需按各片段所附文档链接或已安装 .d.ts 重新核验,若低于 3.4 则建议升级而非编写旧版代码。

【版本说明】v3.5.0 起最低 React Native 为 0.75,peer 范围为 expo >=53 <57;原生组件趋于成熟,iOS 迁移至 Expo Modules,原生与 JS 会话自动双向同步,原生组件认证后不得调用 setActive();配置插件支持主题 JSON 文件定制原生组件样式;下一主版本中原生 Google 登录将迁至独立的 @clerk/expo-google-signin 包,v3 中 @clerk/expo/google 导入仍可用并有开发警告,v3 上不要预装新包。

【常见陷阱】包括生成旧版自定义流程代码、使用 useOAuth()、未确认认证因子启用、原生组件用于 Expo Go/Web、注册页缺少 captcha 挂载点、使用错误的环境变量前缀、未配置 token 缓存导致重启丢失会话、原生组件认证后调用 setActive()、将 AuthView 与原生社交 hooks 配对、手动调用 WebBrowser.maybeCompleteAuthSession()、未经要求拆分登录注册页、守卫中未先检查 isLoaded、用 yalc/pnpm link 本地开发等。

【相关】clerk 为顶层路由;clerk-swift/clerk-android 为原生移动 SDK;clerk-orgs、clerk-billing、clerk-webhooks 为功能技能。参考文档包括 Clerk 官方快速开始(Expo SDK 标签页)、Expo 参考概览,以及 github.com/clerk/clerk-expo-quickstart 提供的三个官方示例应用(纯 JS 的 Expo Go、JS 加原生登录按钮、原生组件)。