auth0-ionic-vue

Auth0 Ionic Vue（Capacitor）集成

使用 Capacitor 为 Ionic Vue 应用添加 Auth0 身份验证。本技能介绍如何使用 @auth0/auth0-vue SDK，结合 @capacitor/browser 和 @capacitor/app 插件，在 iOS 和 Android 上实现原生移动身份验证和深层链接处理。

前提条件

• Node.js 18+
• Ionic CLI（npm install -g @ionic/cli）
• 已配置 Capacitor 的现有 Ionic Vue 应用
• Auth0 账户和租户
• iOS：Xcode 14+ 和 CocoaPods
• Android：Android Studio，且 API 级别为 21+
• Auth0 CLI — brew install auth0/auth0-cli/auth0

不适用场景

使用场景	推荐技能
Vue SPA（不使用 Capacitor/Ionic）	auth0-vue
React SPA（不使用 Capacitor/Ionic）	auth0-react
React Native（裸 CLI）	auth0-react-native
Expo（React Native）	auth0-expo
Ionic + React + Capacitor	auth0-ionic-react
Ionic + Angular + Capacitor	auth0-ionic-angular
Next.js（服务端）	auth0-nextjs
Nuxt（服务端）	auth0-nuxt
iOS 原生（Swift）	auth0-swift
Android 原生（Kotlin）	auth0-android

快速入门工作流

步骤 1：配置 Auth0

使用 Auth0 CLI 自动设置，请参阅设置指南查看完整脚本。

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

步骤 2：安装依赖

npm install @auth0/auth0-vue @capacitor/browser @capacitor/app
npx cap sync

步骤 3：设置 Auth0 插件

Agent 指令： 如果步骤 1 已写入 .env 并更新了 src/main.ts，请确认配置正确，然后跳至步骤 4。仅在手动配置时使用下方模板。

在应用入口点（src/main.ts）注册 Auth0 Vue 插件，并针对 Capacitor 进行配置。凭据通过 import.meta.env 从 .env 中读取：

import { createApp } from 'vue';
import { createAuth0 } from '@auth0/auth0-vue';
import { IonicVue } from '@ionic/vue';
import App from './App.vue';
import router from './router';

// Agent: read appId from capacitor.config.ts and replace this value
const packageId = "YOUR_PACKAGE_ID";

const app = createApp(App);

app.use(IonicVue);
app.use(router);
app.use(
  createAuth0({
    domain: import.meta.env.VITE_AUTH0_DOMAIN,
    clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
    useRefreshTokens: true,
    useRefreshTokensFallback: false,
    authorizationParams: {
      redirect_uri: `${packageId}://${import.meta.env.VITE_AUTH0_DOMAIN}/capacitor/${packageId}/callback`
    }
  })
);

router.isReady().then(() => {
  app.mount('#app');
});

步骤 4：使用 Capacitor Browser 实现登录

<script setup lang="ts">
import { useAuth0 } from '@auth0/auth0-vue';
import { Browser } from '@capacitor/browser';
import { IonButton } from '@ionic/vue';

const { loginWithRedirect } = useAuth0();

const login = async () => {
  await loginWithRedirect({
    async openUrl(url: string) {
      await Browser.open({ url, windowName: "_self" });
    }
  });
};
</script>

<template>
  <ion-button @click="login">Log in</ion-button>
</template>

步骤 5：通过深层链接处理回调

在 App.vue 组件中处理深层链接回调。此操作必须在应用初始化时运行：

<script setup lang="ts">
import { onMounted, onUnmounted } from 'vue';
import { useAuth0 } from '@auth0/auth0-vue';
import { App as CapApp } from '@capacitor/app';
import { Browser } from '@capacitor/browser';
import { IonApp, IonRouterOutlet } from '@ionic/vue';

const { handleRedirectCallback } = useAuth0();

let urlOpenListener: any;

onMounted(async () => {
  urlOpenListener = await CapApp.addListener('appUrlOpen', async ({ url }) => {
    if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
      await handleRedirectCallback(url);
    }
    await Browser.close();
  });
});

onUnmounted(() => {
  urlOpenListener?.remove();
});
</script>

<template>
  <ion-app>
    <ion-router-outlet />
  </ion-app>
</template>

步骤 6：实现注销

<script setup lang="ts">
import { useAuth0 } from '@auth0/auth0-vue';
import { Browser } from '@capacitor/browser';
import { IonButton } from '@ionic/vue';

const domain = import.meta.env.VITE_AUTH0_DOMAIN;
// Agent: read appId from capacitor.config.ts and replace this value
const packageId = "YOUR_PACKAGE_ID";
const logoutUri = `${packageId}://${domain}/capacitor/${packageId}/callback`;

const { logout } = useAuth0();

const doLogout = async () => {
  await logout({
    logoutParams: {
      returnTo: logoutUri
    },
    async openUrl(url: string) {
      await Browser.open({ url, windowName: "_self" });
    }
  });
};
</script>

<template>
  <ion-button @click="doLogout">Log out</ion-button>
</template>

步骤 7：构建和测试

Agent 指令： 集成完成后，请验证构建：

ionic build
npx cap sync

iOS：运行 npx cap open ios，然后在 Xcode 中构建。 Android：运行 npx cap open android，然后在 Android Studio 中构建。 如果构建失败，请最多迭代 5-6 次以修复问题。如果仍然失败，请使用 AskUserQuestion 请求帮助。

详细文档

• 设置指南 — Auth0 CLI 自动设置（登录、创建应用、注入凭据）、Capacitor URL 方案注册、密钥管理
• 集成模式 — 使用 Capacitor Browser 登录/注销、深层链接回调处理、用户资料、受保护路由、令牌访问、错误处理
• 测试与参考 — createAuth0 选项、useAuth0 可组合项、Capacitor 插件配置的完整 API 参考、测试清单、常见问题

常见错误

错误	修正方法
在 Auth0 Dashboard 中未将应用类型设为 Native	在 Dashboard 设置中将应用类型更改为 "Native"
回调 URL 格式缺失或不正确	使用 YOUR_PACKAGE_ID://YOUR_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback — 必须完全匹配
未启用刷新令牌	在 createAuth0() 中设置 useRefreshTokens: true 和 useRefreshTokensFallback: false
缺少 @capacitor/browser 或 @capacitor/app	安装两者：npm install @capacitor/browser @capacitor/app && npx cap sync
未处理深层链接回调	添加 CapApp.addListener('appUrlOpen', ...) 来处理 Auth0 重定向
安装后忘记运行 npx cap sync	安装 Capacitor 插件后务必运行 npx cap sync
将 window.location.origin 用作重定向 URI	使用自定义 URL scheme（packageId://domain/...），不要使用 http://localhost
Dashboard 中缺少 Allowed Origins	将 capacitor://localhost, http://localhost 添加到 Allowed Origins
挂载前未调用 app.use(createAuth0(...))	调用 app.mount('#app') 前注册 Auth0 插件
在 auth refs 上错误地访问 .value	useAuth0() 返回 Vue refs — 在 <script> 中使用 .value，模板会自动解包
将 localStorage 视为可在移动设备上持久保存	使用刷新令牌（useRefreshTokens: true）确保令牌可靠持久保存

WebAuth 方法

此 SDK 通过 Capacitor Browser 插件使用 Auth0 的 Universal Login（WebAuth）。loginWithRedirect() 方法会在系统浏览器中打开 Auth0 授权端点（iOS 上为 SFSafariViewController，Android 上为 Chrome Custom Tabs）。身份验证完成后，Auth0 会使用带有自定义 scheme 的原生回调 URL 将用户重定向回应用：{packageId}://{domain}/capacitor/{packageId}/callback。@capacitor/app 插件会捕获此深层链接，而 handleRedirectCallback(url) 会处理授权码交换。

与使用 https://{domain}/android/{packageId}/callback 或 https://{domain}/ios/{bundleId}/callback 的标准原生 SDK 不同，Ionic Capacitor 应用使用 Capacitor 专用的回调路径，并将包 ID 用作 URL scheme。

相关技能

• auth0-vue — Vue SPA（仅限浏览器，不使用 Capacitor）
• auth0-ionic-react — 使用 React 和 Capacitor 的 Ionic
• auth0-ionic-angular — 使用 Angular 和 Capacitor 的 Ionic
• auth0-react-native — React Native（裸 CLI，不使用 Ionic/Capacitor）
• auth0-expo — 使用 Auth0 的 Expo（React Native）

快速参考

API	描述
createAuth0(options)	Vue 插件工厂 — 使用 app.use() 注册 Auth0
useAuth0()	组合式函数 — 返回 { isLoading, isAuthenticated, user, loginWithRedirect, logout, getAccessTokenSilently, handleRedirectCallback, error }
loginWithRedirect({ openUrl })	通过 Universal Login 登录 — 在 openUrl 回调中使用 Browser.open()
logout({ logoutParams, openUrl })	登出 — 在 openUrl 回调中使用 Browser.open()
handleRedirectCallback(url)	处理来自深层链接的 Auth0 回调 URL
getAccessTokenSilently()	获取访问令牌（在移动设备上使用刷新令牌）
createAuthGuard(app)	用于受保护路由的 Vue Router 导航守卫工厂
Browser.open({ url })	Capacitor — 在系统浏览器中打开 URL（SFSafariViewController / Chrome Custom Tabs）
CapApp.addListener('appUrlOpen', cb)	Capacitor — 监听深层链接事件
Browser.close()	Capacitor — 回调后关闭应用内浏览器

参考资料

• Auth0 Ionic Vue 快速入门
• Auth0 Vue SDK GitHub
• Auth0 Vue SDK API 参考
• Ionic Vue Capacitor 示例应用
• Capacitor Browser 插件
• Capacitor App 插件
• Auth0 控制面板