clerk-auth-expert

Clerk 身份验证专家

你是 Clerk 身份验证专家，深入了解适用于 React Native 和 Expo 应用的 Clerk 生态系统。此技能可帮助你为 N8ture AI App 实现安全且适用于生产环境的身份验证流程。

核心职责

• 实现 Clerk SDK - 正确配置 @clerk/clerk-expo
• 身份验证流程 - 构建登录、注册、密码重置和社交身份验证流程
• 会话管理 - 处理用户会话、令牌刷新和持久化
• 受保护的路由 - 为导航创建身份验证守卫
• 用户管理 - 访问和更新用户个人资料及元数据
• 后端集成 - 将 Clerk JWT 令牌传递给 Firebase Cloud Functions

快速开始

安装

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

基本设置

// App.js
import { ClerkProvider } from '@clerk/clerk-expo';
import * as SecureStore from 'expo-secure-store';

const tokenCache = {
  async getToken(key) {
    return SecureStore.getItemAsync(key);
  },
  async saveToken(key, value) {
    return SecureStore.setItemAsync(key, value);
  },
};

export default function App() {
  return (
    <ClerkProvider 
      publishableKey={process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY}
      tokenCache={tokenCache}
    >
      <RootNavigator />
    </ClerkProvider>
  );
}

常见模式

受保护的路由

import { useAuth } from '@clerk/clerk-expo';

export function useProtectedRoute() {
  const { isSignedIn, isLoaded } = useAuth();
  const navigation = useNavigation();

  useEffect(() => {
    if (isLoaded && !isSignedIn) {
      navigation.navigate('SignIn');
    }
  }, [isSignedIn, isLoaded]);

  return { isSignedIn, isLoaded };
}

访问用户个人资料

import { useUser } from '@clerk/clerk-expo';

export function ProfileScreen() {
  const { user } = useUser();

  const updateProfile = async () => {
    await user.update({
      firstName: 'John',
      lastName: 'Doe',
    });
  };

  return (
    <View>
      <Text>Welcome, {user.firstName}!</Text>
      <Text>Email: {user.primaryEmailAddress.emailAddress}</Text>
    </View>
  );
}

传递后端令牌

import { useAuth } from '@clerk/clerk-expo';

export function useAuthenticatedRequest() {
  const { getToken } = useAuth();

  const makeRequest = async (endpoint, data) => {
    const token = await getToken();
    
    const response = await fetch(endpoint, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(data),
    });

    return response.json();
  };

  return { makeRequest };
}

N8ture AI App 集成

试用管理

将用户试用次数存储在 Clerk 用户元数据中：

// Update trial count
await user.update({
  unsafeMetadata: {
    trialCount: 3,
    totalIdentifications: 0,
  },
});

// Check trial status
const trialCount = user.unsafeMetadata.trialCount || 0;
const canIdentify = user.publicMetadata.isPremium || trialCount > 0;

高级订阅状态

// Store subscription status
await user.update({
  publicMetadata: {
    isPremium: true,
    subscriptionId: 'sub_xxx',
  },
});

最佳实践

1. 使用令牌缓存 - 始终实现 SecureStore 令牌缓存
2. 处理加载状态 - 在渲染依赖身份验证的 UI 前检查 isLoaded
3. 保护元数据 - 使用 publicMetadata 存储非敏感数据，使用 privateMetadata 存储敏感数据
4. 错误处理 - 妥善处理身份验证失败
5. 社交身份验证 - 实施前先在 Clerk Dashboard 中配置 OAuth 提供商

环境变量

# .env
EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxxxx

常见问题

问题：“Clerk 尚未加载”
**解决方案：**访问身份验证状态前始终检查 isLoaded

**问题：**令牌未持久化
**解决方案：**确保正确配置 SecureStore 令牌缓存

**问题：**社交身份验证无法正常工作
**解决方案：**在 Clerk Dashboard 和 app.json 中配置 OAuth 重定向 URL

资源

• Clerk Expo 文档
• Clerk React Native SDK
• 身份验证最佳实践

在实现身份验证、管理用户会话或将 Clerk 与 N8ture AI App 后端集成时，请使用此技能。