Auth0 Expo 集成

使用 react-native-auth0 和 Expo 配置插件，为 Expo（React Native）应用添加身份验证功能。

Agent 指令：在提供 SDK 设置说明前，请先运行以下命令获取最新发布版本：

gh api repos/auth0/react-native-auth0/releases/latest --jq '.tag_name'

将该命令返回的版本号用于所有依赖项声明中，替换下方所有硬编码的版本号。若该命令执行失败，请回退至访问 https://github.com/auth0/react-native-auth0/releases 查看最新版本。

前提条件

• Expo SDK 53 或更高版本（react-native-auth0 v5.x 要求 Expo 53+）
• React 19 及 React Native 0.78.0 或更高版本
• Node.js 20+（用于启动脚本自动化）
• 已配置好 Native 类型应用的 Auth0 账户
• 若尚未配置 Auth0，请先使用 auth0-quickstart 技能
• 不兼容 Expo Go —— 必须使用自定义开发客户端或 EAS Build

不适用场景

快速入门工作流

Agent 指令：首先检查用户提示中是否已同时提供 Auth0 的 Client ID 和 Domain。

• 若两者均已提供，则跳过“配置方式选择”提问，直接进入 步骤 2（验证 Expo 开发客户端） 并使用这些值。
• 若任一值缺失，请使用 AskUserQuestion 向用户提问：“您希望如何为此 Expo 项目配置 Auth0？”
  • 自动配置（推荐） —— 运行启动脚本，自动创建 Auth0 应用、数据库连接、回调 URL，并将插件配置写入 app.json
  • 手动配置 —— 用户自行提供 Auth0 Client ID 和 Domain

根据用户的选择，执行下方对应章节中的操作。

1. 配置 Auth0

自动配置

Agent 指令：在运行启动脚本前，请先执行以下快速检查。请 不要 由 Agent 执行 auth0 login —— 该命令为交互式，会导致阻塞。

1. 检查 Node.js 版本：node --version。若未安装或版本低于 20，请向用户询问：是否安装（brew install node），或切换至手动配置。
2. 检查 Auth0 CLI 是否存在：command -v auth0。若未安装，请向用户询问：是否安装（brew install auth0/auth0-cli/auth0），或切换至手动配置。
3. 检查 Auth0 登录状态：auth0 tenants list --csv --no-input 2>&1。若执行失败或返回空结果：
   • 告知用户：“请在终端中运行 auth0 login，完成后通知我。”
   • 等待用户确认后，重新运行该检查以验证登录状态。
4. 确认当前租户：解析 CSV 输出中含 → 的行，识别当前活跃租户域名。告知用户：“您的当前 Auth0 租户为：。该租户是否正确？”
   • 若正确，继续下一步。
   • 若不正确，请用户在终端中运行 auth0 tenants use ，然后重新执行第 3 步以确认新的活跃租户。

确认无误后，运行启动脚本：

cd /auth0-expo/scripts
npm install
node bootstrap.mjs 

该脚本将校验 Expo 项目、创建 Native 类型的 Auth0 应用、配置数据库连接，并将插件配置写入 app.json。Agent 不应手动处理 client_id 或 domain。

若脚本因会话过期失败，请让用户再次运行 auth0 login，然后重试脚本。其他失败情形请回退至下方的 手动配置。

脚本成功执行后，进入 步骤 2（验证 Expo 开发客户端）。

手动配置（用户提供的凭据）

Agent 指令：请使用 AskUserQuestion 向用户请求 Auth0 凭据：

“我需要您的 Auth0 凭据来配置身份验证。请提供：

1. Auth0 Domain（例如：your-tenant.us.auth0.com）
2. Client ID（32 位字母数字字符串）

您可在 Auth0 控制台的 Applications > Applications > your app > Settings 中找到这两项。若您尚未创建 Auth0 应用，请新建一个类型为 Native 的应用，并从设置页面复制 Domain 和 Client ID。”

随后将配置写入 app.json，并进入 步骤 2。

2. 验证 Expo 开发客户端

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 配置插件

在 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 及密钥管理，请参阅 配置指南。

Agent 指令：若您使用了自动配置（步骤 1），启动脚本已将插件配置写入 app.json —— 请验证其内容是否正确，但无需覆盖。若使用手动配置，请使用用户提供的 Domain 和自定义 scheme 现在写入配置。

5. 配置回调 URL

在 Auth0 控制台的 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 ;
  }

  return (
    
      {user ? (
        <>
          Welcome, {user.name}!
          {user.email}
          
        
      ) : (
        
      )}
      {error && {error.message}}
    
  );
}

export default function App() {
  return (
    
      
    
  );
}

7. 构建与验证

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

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 —— 请检查插件配置是否正确
• iOS 下 Pod install 失败：运行 npx expo prebuild --clean 以重新生成原生项目
• Android 下 Manifest 合并失败：auth0Domain 占位符冲突 —— 请确保仅由配置插件设置该 Domain

每次修复后均需重新运行构建。请记录构建-修复迭代次数。

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

• 让技能继续迭代修复
• 手动修复 —— 展示剩余错误信息
• 跳过构建验证 —— 不依赖成功构建而继续

详细文档

• 配置指南 —— 开发客户端要求、自动配置流程、Expo 配置插件、回调 URL、EAS Build、密钥管理
• 集成模式 —— 登录/登出、凭据管理、生物特征认证、Token 刷新、组织支持、DPoP、错误处理
• API 参考与测试 —— 配置选项、useAuth0 Hook API、测试清单、常见问题、安全性

常见错误

相关技能

• auth0-quickstart —— 配置 Auth0 账户及应用
• auth0-react-native —— Bare React Native CLI 项目
• auth0-mfa —— 配置多因素认证
• auth0-cli —— 通过终端管理 Auth0 资源

参考资料

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