This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

使用 Clerk

编辑页面

了解如何在你的 Expo 和 React Native 项目中添加 Clerk 身份验证和用户管理。

Android
iOS
Web

Clerk 是一个身份验证和用户管理平台,提供注册、登录、多因素身份验证、社交登录、组织以及托管用户数据库等功能。@clerk/expo SDK 为你提供 React hooks、控制组件、托管身份验证,以及预构建的原生 UI 组件。这些组件在 Android 上使用 Jetpack Compose 渲染,在 iOS 上使用 SwiftUI 渲染。

本指南将介绍如何安装 @clerk/expo、将应用包装在 <ClerkProvider> 中,以及如何选择适合项目的集成方式。本指南面向 @clerk/expo 4.x,该版本支持 Expo SDK 54 及更高版本。

选择你的集成方式

@clerk/expo 支持三种方式。请选择符合你需求的方式。之后你可以随时切换,而无需重写应用。

方式你需要构建的内容可在 Expo Go 中运行最适合
托管身份验证一个按钮,用于在浏览器身份验证会话中打开 Clerk 的账户门户最快速的设置方式,并启用控制面板中的所有方法
原生 UI 组件@clerk/expo/native 中直接使用 <AuthView /><UserButton /><UserProfileView />完整的原生登录和账户管理 UI
自定义流程自行构建 React Native 界面,并调用 useSignUp()useSignIn() 等 hooks最大程度的 UI 控制

前置条件

Prerequisites

4 requirements

1.

创建 Clerk 账户和应用

Clerk Dashboard 注册并创建一个应用。

2.

启用 Native API

打开 Clerk Dashboard 中的 Native applications 页面,并确保 Native API 已开启。对于任何使用 @clerk/expo 的 Expo 集成都需要这样做。

3.

使用 Expo SDK 53 或更高版本

@clerk/expo Core 3 的 peer dependency 是 expo: >=53 <56

4.

为原生功能使用开发构建版本

原生 UI 组件和原生登录 hooks 需要开发构建版本。托管身份验证和自定义流程也可以在 Expo Go 中运行。

安装并配置 Clerk

1

安装 @clerk/expoexpo-secure-store

使用 npx expo install,以确保版本与你的 Expo SDK 匹配:

Terminal
npx expo install @clerk/expo expo-secure-store

expo-secure-store 是一个 peer dependency。Clerk 通过 @clerk/expo/token-cache 使用它,利用 iOS Keychain 和 Android Keystore 对会话令牌进行加密。

对于托管身份验证,还需要安装 Clerk 用于打开浏览器身份验证会话的包:

Terminal
npx expo install expo-auth-session expo-crypto expo-web-browser

如果你计划在自定义流程中添加原生使用 Google 登录的按钮,请安装 @clerk/expo-google-signinexpo-crypto

Terminal
npx expo install @clerk/expo-google-signin expo-crypto

对于原生使用 Apple 登录的按钮,请同时安装 expo-apple-authenticationexpo-crypto

Terminal
npx expo install expo-apple-authentication expo-crypto

如果你只使用 @clerk/expo/native 中的 <AuthView />,则不需要这些额外包,因为该组件会在内部处理社交登录流程。

2

验证配置插件

@clerk/expoexpo-secure-store 添加到 应用配置 中的 plugins 数组。如果你的项目使用静态 app.json,并且通过 npx expo install 安装了这些包,Expo 已经为你添加了它们:

app.json
{ "expo": { "plugins": ["expo-secure-store", "@clerk/expo"] } }

@clerk/expo 插件会添加 Apple 登录 entitlement(如果应用不使用 Apple 登录,可以通过插件选项 appleSignIn: false 将其禁用)、为托管身份验证回调注册 Android intent filter,并应用底层 clerk-android SDK 所需的 Android 打包修复。如果你使用原生使用 Google 登录的按钮,还需要将 @clerk/expo-google-signin 插件一并添加。

托管身份验证会根据应用配置中的 android.packageios.bundleIdentifier 值生成默认回调。在创建生产构建版本之前,请在 Clerk Dashboard 的 Native applications 页面添加应用,并使用相同的 Android package name 和 iOS bundle identifier,因为生产实例会根据已注册的值验证回调。

3

添加你的 Clerk Publishable Key

从 Clerk Dashboard 的 API keys 页面复制你的 Publishable Key,然后将其添加到项目根目录的 .env 文件中:

.env
EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_your-key-here

必须使用 EXPO_PUBLIC_ 前缀,因为 Expo 会在构建时内联这些值,从而使它们可在 JavaScript bundle 中使用。Clerk 的 Publishable Key 可以安全公开。不要 将 Secret Keys 放在 EXPO_PUBLIC_ 前缀之后。

4

将你的应用包装在 <ClerkProvider>

在根布局文件中(使用 Expo Router 时为 src/app/_layout.tsx),将应用包装在 <ClerkProvider> 中并传入 Publishable Key。建议显式传入 tokenCache

src/app/_layout.tsx
import { ClerkProvider } from '@clerk/expo'; import { tokenCache } from '@clerk/expo/token-cache'; import { Slot } from 'expo-router'; const publishableKey = process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY!; if (!publishableKey) { throw new Error('将你的 Clerk Publishable Key 添加到 .env 文件中'); } export default function RootLayout() { return ( <ClerkProvider publishableKey={publishableKey} tokenCache={tokenCache}> <Slot /> </ClerkProvider> ); }

在 Core 3 中,Expo 应用的 <ClerkProvider> 需要 publishableKey。生产环境的 React Native 构建中,node_modules 内部的环境变量不会被内联,因此必须显式传入该属性。

来自 @clerk/expo/token-cachetokenCache 使用 expo-secure-store 持久化用户会话,以便在应用重启后仍能保留。显式传入它可以让依赖关系更清晰,并且以后也能轻松替换为自定义缓存实现。

添加身份验证

下一步取决于你选择的方式。下面的选项卡展示了每种方式所需的最少代码。

托管身份验证会在应用上方的浏览器身份验证会话中打开 Clerk 的账户门户。用户可以完成 Clerk 应用中启用的任意登录或注册方式,SDK 会在应用中激活生成的会话。调用 useHostedAuth() hook 中的 startHostedAuth()

src/app/index.tsx
import { useAuth } from '@clerk/expo'; import { useHostedAuth } from '@clerk/expo/hosted-auth'; import { ActivityIndicator, Button, Text, View } from 'react-native'; export default function MainScreen() { const { isLoaded, isSignedIn } = useAuth(); const { startHostedAuth } = useHostedAuth(); const handleSignUp = async () => { try { await startHostedAuth({ mode: 'sign-up' }); } catch (error) { // 在应用中处理错误 } }; if (!isLoaded) { return <ActivityIndicator size="large" />; } return ( <View> {isSignedIn ? ( <Text>You're signed in</Text> ) : ( <Button title="Sign up" onPress={handleSignUp} /> )} </View> ); }

身份验证完成后,SDK 会关闭浏览器会话、激活新会话,并使用已登录状态更新 useAuth()。浏览器不会保留单独的活动会话。

startHostedAuth() 默认打开登录页面,并接受 mode: 'sign-in' | 'sign-up'。如果用户在完成身份验证前关闭浏览器,它会以 createdSessionIdnull 的结果解决;身份验证失败时则会抛出异常。

这种方式可以在 Expo Go 中运行,此时 Expo 会提供开发回调。在开发构建或生产构建中,回调会根据你的 iOS bundle identifier 或 Android package name 生成,因此请将 @clerk/expo 配置插件保留在应用配置中,并在修改任一标识符后重新构建原生项目。

账户门户运行在浏览器中,因此社交登录使用各提供商的 Web OAuth 流程,而不是原生流程。请参阅托管身份验证指南,了解生产凭证要求和故障排除方法。

读取已登录用户

在应用的任何位置,使用 useUser()useAuth() 读取用户数据,再加上 <Show>useClerk() 来保护内容并执行登出:

import { Show, useClerk, useUser } from '@clerk/expo'; import { Link } from 'expo-router'; import { Pressable, Text, View } from 'react-native'; export default function HomeScreen() { const { user } = useUser(); const { signOut } = useClerk(); return ( <View> <Show when="signed-in"> <Text>你好,{user?.firstName ?? 'friend'}</Text> <Pressable onPress={() => signOut()}> <Text>登出</Text> </Pressable> </Show> <Show when="signed-out"> <Link href="/(auth)/sign-in"> <Text>登录</Text> </Link> </Show> </View> ); }

<Show> 取代了该 SDK 早期版本中的旧 <SignedIn><SignedOut><Protect> 组件。它还支持 when={{ role: '...' }}when={{ permission: '...' }} 以及其他授权谓词。

运行应用

对于托管身份验证和自定义流程,请运行以下命令,然后在 Expo Go 中打开项目:

Terminal
npx expo start

后续步骤

Clerk Expo 快速开始

逐步说明如何设置三种集成方式,并提供 GitHub 上的配套仓库。

托管身份验证

使用 Clerk 的账户门户在 Expo 应用中为用户完成登录和注册,并了解回调、取消处理和生产环境设置。

原生组件参考

AuthView、UserButton 和 UserProfileView 的 API 参考,包括配置、主题和平台要求。

使用 Google 登录

通过 Clerk Dashboard 和 Google Cloud Console 为 Android 和 iOS 设置原生使用 Google 登录。

使用 Apple 登录

配置原生 Apple 登录,以满足 App Store 指南 4.8。

保护内容并读取用户数据

在你的 Expo 应用中使用 Clerk 的 hooks 和 Show 组件来保护路由并访问用户数据。

使用 Clerk 将 Expo 应用部署到生产环境

配置生产凭证、允许移动端 SSO 重定向,并使用 EAS Build 发布。