auth0-expo

用途

auth0-expo 用于在 Expo（React Native）应用中添加 Auth0 登录、登出或会话管理。它把 react-native-auth0 与 Expo Config Plugin 集成，为原生 iOS/Android 应用提供认证能力。

前置条件

Expo SDK 53 或更高（react-native-auth0 v5.x 要求 Expo 53+）
React 19 与 React Native 0.78.0 或更高
已配置 Native 应用的 Auth0 账户
若尚未设置 Auth0，请先使用 auth0-quickstart 技能
不兼容 Expo Go，需要自定义开发客户端或 EAS Build

不适用场景

裸 React Native CLI 项目（无 Expo）：使用 auth0-react-native
React Web SPA（Vite/CRA）：使用 auth0-react
Next.js 应用：使用 auth0-nextjs
Vue.js SPA：使用 auth0-vue
Angular SPA：使用 auth0-angular
Express.js 后端：使用 auth0-express
原生 Android（Kotlin/Java）：使用 auth0-android
后端 API（JWT 校验）：使用 auth0-fastify-api 或 auth0-express

快速开始流程

1. 配置 Auth0

使用 Auth0 CLI 自动设置可参考 Setup Guide 中的完整脚本。手动设置则在 Auth0 Dashboard 中配置 Native 应用，并记录 Domain 与 Client ID。

2. 验证 Expo Dev Client

在安装 Auth0 SDK 前，检查项目是否已安装 expo-dev-client（读取 package.json 的 dependencies 或 devDependencies）。

若已找到：进入第 3 步。
若未找到：需询问用户如何继续。选项一为自动安装，运行：

npx expo install expo-dev-client

选项二为跳过此步，直接进入第 3 步。

3. 安装 SDK

npx expo install react-native-auth0

4. 配置 Expo Config Plugin

在 app.json（或 app.config.js）中添加 react-native-auth0 插件，填入 Auth0 domain 与自定义 scheme，并确保设置了 bundleIdentifier（iOS）与 package（Android）：

{
  "expo": {
    "ios": { "bundleIdentifier": "com.yourcompany.yourapp" },
    "android": { "package": "com.yourcompany.yourapp" },
    "plugins": [
      ["react-native-auth0", {
        "domain": "YOUR_AUTH0_DOMAIN",
        "customScheme": "YOUR_CUSTOM_SCHEME"
      }]
    ]
  }
}

customScheme 必须全小写且不含特殊字符（例如 auth0sample）。HTTPS 回调、多域名、EAS Build 与密钥管理参见 Setup Guide。

5. 配置回调 URL

在 Auth0 Dashboard 的 Allowed Callback URLs 与 Allowed Logout URLs 中添加：

YOUR_CUSTOM_SCHEME://YOUR_AUTH0_DOMAIN/ios/YOUR_BUNDLE_ID/callback,
YOUR_CUSTOM_SCHEME://YOUR_AUTH0_DOMAIN/android/YOUR_PACKAGE/callback

所有值必须小写且无尾部斜杠。HTTPS 回调 URL（App Links / Universal Links）参见 Setup Guide。

6. 使用 Auth0Provider 添加认证

用 Auth0Provider 包裹应用并使用 useAuth0 钩子。在添加新 UI 元素前，先搜索项目中已有的登录、登出、sign-in 或 sign-out 按钮点击处理器；若存在则接入 Auth0 代码，仅在无现有处理器时创建新按钮。

import React from 'react';
import { Auth0Provider, useAuth0 } from 'react-native-auth0';
import { View, Button, Text, ActivityIndicator } from 'react-native';

function HomeScreen() {
  const { authorize, clearSession, user, isLoading, error } = useAuth0();

  const login = async () => {
    try {
      await authorize(
        { scope: 'openid profile email' },
        { customScheme: 'YOUR_CUSTOM_SCHEME' }
      );
    } catch (e) {
      console.error('Login error:', e);
    }
  };

  const logout = async () => {
    try {
      await clearSession({ customScheme: 'YOUR_CUSTOM_SCHEME' });
    } catch (e) {
      console.error('Logout error:', e);
    }
  };

  if (isLoading) {
    return <ActivityIndicator size="large" />;
  }

  return (
    <View>
      {user ? (
        <>
          <Text>Welcome, {user.name}!</Text>
          <Text>{user.email}</Text>
          <Button title="Log Out" onPress={logout} />
        </>
      ) : (
        <Button title="Log In" onPress={login} />
      )}
      {error && <Text>{error.message}</Text>}
    </View>
  );
}

export default function App() {
  return (
    <Auth0Provider
      domain="YOUR_AUTH0_DOMAIN"
      clientId="YOUR_AUTH0_CLIENT_ID"
    >
      <HomeScreen />
    </Auth0Provider>
  );
}

7. 构建与验证

完成集成后构建项目以验证可编译：

npx expo prebuild --clean
npx expo run:ios
# 或
npx expo run:android

若构建失败，分析错误输出。常见集成构建失败包括：

“Invariant Violation: Native module cannot be null”：使用了 Expo Go 而非开发构建，应运行 npx expo run:ios 或 npx expo run:android，而非 npx expo start
插件未应用：app.json 的 plugins 数组缺少 react-native-auth0，检查插件配置
Pod install 失败（iOS）：运行 npx expo prebuild --clean 重新生成原生项目
Manifest 合并失败（Android）：auth0Domain 占位符冲突，确保仅由 config plugin 设置 domain

每次修复后重新构建，并记录构建修复迭代次数。若经过 5–6 次修复尝试后仍失败，停止并询问用户如何继续：让技能继续迭代修复、手动修复并显示剩余错误、或跳过构建验证。

详细文档

Setup Guide：Dev client 要求、自动设置、Expo config plugin、回调 URL、EAS Build、密钥管理
Integration Patterns：登录/登出、凭据管理、生物识别认证、令牌刷新、组织、DPoP、错误处理
API Reference & Testing：配置选项、useAuth0 钩子 API、测试清单、常见问题、安全

常见错误

使用 Expo Go 而非开发构建：react-native-auth0 需要原生代码，应使用 npx expo run:ios / npx expo run:android 或通过 EAS 创建开发构建。
authorize/clearSession 调用缺少 customScheme：将 { customScheme: 'your-scheme' } 作为第二个参数传入，且必须与 app.json 插件配置一致。
回调 URL 不匹配：确保回调 URL 全小写、无尾部斜杠，并与 Auth0 Dashboard 完全一致：{customScheme}://{domain}/ios/{bundleId}/callback。
应用类型未设为 Native：Auth0 应用在 Dashboard 中必须为 Native 类型，而非 SPA 或 Regular Web。
app.json 缺少 bundleIdentifier 或 package：必须同时设置 expo.ios.bundleIdentifier 与 expo.android.package，回调 URL 才能工作。
忘记用 Auth0Provider 包裹应用：所有使用 useAuth0() 的组件必须是 Auth0Provider 的子组件。
在 Expo < 53 上使用 react-native-auth0 v5.x：v5.x 要求 Expo 53+，旧版 Expo 应使用 v4.x。
未在物理设备上测试：生物识别认证（Face ID、指纹）仅在物理设备上有效，模拟器不支持。发布前务必在真机上测试完整认证流程。

参考资料

Auth0 Expo Quickstart
react-native-auth0 GitHub Repository
react-native-auth0 API Documentation
Expo Sample App
EXAMPLES.md

技能介绍

用途