auth0-expo

Auth0 Expo 集成

使用 react-native-auth0 和 Expo Config Plugin 为 Expo（React Native）应用添加身份验证。

前提条件

• 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

以下情况请勿使用

使用场景	推荐技能
Bare 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 自动设置，请参阅设置指南了解完整脚本。

手动设置时，请在 Auth0 Dashboard 中配置一个 Native 应用，并记下 Domain 和 Client ID。

2. 验证 Expo Dev Client

Agent 说明： 安装 Auth0 SDK 前，请检查项目是否已安装 expo-dev-client。读取项目的 package.json，并在 dependencies 或 devDependencies 中查找 expo-dev-client。

• 如果找到 expo-dev-client： 继续执行第 3 步。

• 如果未找到 expo-dev-client： 使用 AskUserQuestion 询问以下内容：

  “react-native-auth0 SDK 需要自定义 Expo 开发客户端——它不能与 Expo Go 配合使用。你的项目尚未安装 expo-dev-client。

  你希望如何继续？

  1. 帮我安装——我会运行 npx expo install expo-dev-client 并继续设置
  2. 我会自行设置——跳过此步骤，继续安装 Auth0 SDK”

  如果用户选择选项 1，请运行：

  npx expo install expo-dev-client
  

  然后继续执行第 3 步。如果选择选项 2，则直接继续执行第 3 步。

3. 安装 SDK

npx expo install react-native-auth0

4. 配置 Expo Config Plugin

将 react-native-auth0 插件添加到 app.json（或 app.config.js），并填写你的 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 和密钥管理，请参阅设置指南。

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），请参阅设置指南。

6. 使用 Auth0Provider 添加身份验证

使用 Auth0Provider 包装应用，并使用 useAuth0 hook：

Agent 说明： 添加新的 UI 元素之前，请在项目中搜索登录、注销、登录或退出按钮现有的点击处理程序。如果找到现有处理程序，请将 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. 构建与验证

Agent 指令： 完成集成后，构建项目以验证其能否编译：

npx expo prebuild --clean
npx expo run:ios
# or
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 插件数组中缺少 react-native-auth0——请检查插件配置
• Pod 安装失败（iOS）：运行 npx expo prebuild --clean 以重新生成原生项目
• 清单合并失败（Android）：auth0Domain 占位符冲突——确保只有配置插件设置该域名

每次修复后都重新运行构建。记录构建修复迭代次数。

失败检查： 如果尝试修复 5–6 次后构建仍然失败，请停止并使用 AskUserQuestion 询问用户： “经过多次修复尝试，构建仍然失败。你希望如何继续？”

• 让该技能继续逐步修复
• 手动修复——显示剩余错误
• 跳过构建验证——在构建未成功的情况下继续

详细文档

• 设置指南 — 开发客户端要求、自动化设置、Expo 配置插件、回调 URL、EAS Build、机密管理
• 集成模式 — 登录/登出、凭据管理、生物识别身份验证、令牌刷新、组织、DPoP、错误处理
• API 参考与测试 — 配置选项、useAuth0 hook API、测试清单、常见问题、安全性

常见错误

错误	修复方法
使用 Expo Go 而非开发构建	react-native-auth0 需要原生代码。请使用 npx expo run:ios / npx expo run:android，或使用 EAS 创建开发构建。
在 authorize/clearSession 调用中缺少 customScheme	将 { customScheme: 'your-scheme' } 作为第二个参数传给 authorize() 和 clearSession()。该值必须与 app.json 插件配置中的值一致。
回调 URL 不匹配	确保回调 URL 全部使用小写字母、末尾没有斜杠，并且与 Auth0 Dashboard 完全一致：{customScheme}://{domain}/ios/{bundleId}/callback
未将应用类型设为 Native	Auth0 应用在 Dashboard 中必须设为 Native 类型，不能设为 SPA 或 Regular Web。
app.json 中缺少 bundleIdentifier 或 package	要使回调 URL 正常工作，必须在 app.json 中设置 expo.ios.bundleIdentifier 和 expo.android.package。
忘记使用 Auth0Provider 包裹应用	所有使用 useAuth0() 的组件都必须是 Auth0Provider 的子组件。
在 Expo < 53 中使用 react-native-auth0 v5.x	5.x 版本需要 Expo 53+。较旧的 Expo 版本请使用 v4.x。
未在实体设备上测试	生物识别身份验证（Face ID、指纹）只能在实体设备上使用，不能在模拟器上使用。发布前务必在真实设备上测试完整的身份验证流程。

相关技能

• auth0-quickstart — 设置 Auth0 账户和应用
• auth0-react-native — 裸 React Native CLI 项目
• auth0-mfa — 配置多因素身份验证
• auth0-cli — 从终端管理 Auth0 资源

参考资料

• Auth0 Expo 快速入门
• react-native-auth0 GitHub 仓库
• react-native-auth0 API 文档
• Expo 示例应用
• EXAMPLES.md