auth0-spa-js

Auth0 SPA JS 集成

使用 @auth0/auth0-spa-js 为任何基于浏览器的单页应用添加身份验证。它是适用于 Vanilla JS、Svelte、SolidJS 以及任何不使用 React、Angular 或 Vue 的 SPA 的底层 Auth0 SDK。

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

gh api repos/auth0/auth0-spa-js/releases/latest --jq '.tag_name'

在所有依赖项行中使用命令返回的版本，不要使用下方的任何硬编码版本。如果命令失败，请转而查看 https://github.com/auth0/auth0-spa-js/releases。

先决条件

• 支持 ES2017+ 的现代浏览器
• npm 或 yarn（不使用打包工具的应用也可以使用 CDN）
• 已配置单页应用的 Auth0 账户
• 如果尚未设置 Auth0，请参阅 auth0-quickstart

不适用场景

• React SPA（hooks、Auth0Provider）：使用 auth0-react
• Angular SPA（AuthModule、AuthGuard）：使用 auth0-angular
• Vue 3 SPA（createAuth0、useAuth0）：使用 auth0-vue
• Next.js（服务器端会话、App Router）：使用 auth0-nextjs
• Nuxt（服务器端 SSR）：使用 auth0-nuxt
• Express 服务器端 Web 应用：使用 auth0-express
• React Native / Expo 移动应用：使用 auth0-react-native

快速入门工作流

1. 安装 SDK

npm install @auth0/auth0-spa-js

也可以通过 CDN 使用（不需要打包工具）。运行以下命令获取最新版本，然后在 HTML 中使用：

VERSION=$(npm view @auth0/auth0-spa-js version)

<script src="https://cdn.auth0.com/js/auth0-spa-js/$VERSION/auth0-spa-js.production.js"></script>

2. 配置 Auth0

如需通过 Auth0 CLI 自动设置，请参阅 设置指南，了解完整脚本。

如需手动设置，请创建 .env（Vite）：

VITE_AUTH0_DOMAIN=your-tenant.auth0.com
VITE_AUTH0_CLIENT_ID=your-client-id

在 Auth0 Dashboard 中，为你的单页应用设置：

• 允许的回调 URL：http://localhost:5173
• 允许的注销 URL：http://localhost:5173
• 允许的 Web 来源：http://localhost:5173

3. 初始化 Auth0 客户端

import { createAuth0Client } from '@auth0/auth0-spa-js';

const auth0 = await createAuth0Client({
  domain: import.meta.env.VITE_AUTH0_DOMAIN,
  clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
  authorizationParams: {
    redirect_uri: window.location.origin
  }
});

// Handle redirect callback after login
const query = new URLSearchParams(window.location.search);
if ((query.has('code') || query.has('error')) && query.has('state')) {
  await auth0.handleRedirectCallback();
  window.history.replaceState({}, document.title, window.location.pathname);
}

4. 添加登录 / 注销功能

Agent 指令： 添加新的 UI 元素之前，请在项目中搜索登录、注销、登入或登出按钮现有的点击处理程序。如果找到现有处理程序，请将 Auth0 代码接入其中，不要修改现有 UI。只有在找不到现有处理程序时，才创建新按钮。

// Login
document.getElementById('login-btn').addEventListener('click', async () => {
  await auth0.loginWithRedirect();
});

// Logout
document.getElementById('logout-btn').addEventListener('click', () => {
  auth0.logout({
    logoutParams: { returnTo: window.location.origin }
  });
});

// Update UI based on auth state
const isAuthenticated = await auth0.isAuthenticated();
if (isAuthenticated) {
  const user = await auth0.getUser();
  console.log(user.name, user.email);
}

5. 获取 API 调用所需的访问令牌

const accessToken = await auth0.getTokenSilently();

const response = await fetch('https://your-api.example.com/data', {
  headers: { Authorization: `Bearer ${accessToken}` }
});

6. 构建并验证

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

npm run build

如果构建失败，请分析错误输出并修复问题。常见的集成构建失败包括：

• 找不到模块：缺少 npm install @auth0/auth0-spa-js — 运行安装命令
• 找不到名称 'import.meta'：TypeScript 目标版本过低 — 在 tsconfig.json 中将 "target": "ES2020" 或更高版本
• createAuth0Client 不是函数：导入路径错误，或未经过打包步骤就使用 CDN
• 运行时环境变量未定义：Vite 要求使用 VITE_ 前缀；webpack/CRA 要求使用 REACT_APP_ 前缀

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

失败检查： 如果经过 5–6 次修复尝试后构建仍然失败，请停止并通过 AskUserQuestion 询问用户： "经过几次修复尝试后，构建仍然失败。你想如何继续？"

• 让此技能继续迭代修复 — 再进行 5–6 次构建修复循环
• 手动修复 — 显示剩余错误，让用户自行解决
• 跳过构建验证 — 未成功构建也继续

详细文档

• 设置指南 — 自动化设置脚本（Bash/PowerShell）、Auth0 CLI 命令、.env 配置、回调 URL 设置
• 集成模式 — 令牌管理、调用 API、刷新令牌、组织、MFA、DPoP、错误处理、高级模式
• 测试与参考 — 配置选项、声明参考、测试清单、常见问题、安全注意事项

常见错误

错误	修复方法
回调 URL 端口不匹配（例如，localhost:3001 与 localhost:5173）	在 Auth0 Dashboard 中，将 Allowed Callback URLs 与开发服务器端口完全匹配
在 SPA 代码中使用 client_secret	SPA 绝不能有客户端密钥——请将其移除。Auth0 会将 SPA 应用的身份验证方法设为 None
将令牌存储在 localStorage 中	使用内存存储（默认）或 sessionStorage。绝不要使用 localStorage——这会带来 XSS 风险
页面刷新时，getTokenSilently() 抛出 login_required	在 Auth0 Dashboard 的 Allowed Web Origins 中添加应用源
重定向后未调用 handleRedirectCallback()	登录重定向后必须调用此方法以交换授权码；否则 URL 参数会保留并再次触发
域名包含 https:// 前缀	Auth0 域名应仅包含主机名：your-tenant.auth0.com，而不是 https://your-tenant.auth0.com
在异步初始化代码中调用 loginWithPopup()	弹出窗口必须由用户操作直接触发（点击处理程序）。绝不要在初始化或页面加载代码中调用
在 Vanilla JS 中使用来自 @auth0/auth0-react 的 Auth0Provider	对于 Vanilla JS，请直接使用 createAuth0Client()——无需 Provider 组件

相关技能

• auth0-quickstart — 设置 Auth0 账户和应用
• auth0-react — 面向 React SPA 的 Auth0 与 Hooks
• auth0-angular — 面向 Angular SPA 的 Auth0
• auth0-vue — 面向 Vue 3 SPA 的 Auth0
• auth0-mfa — 添加多重身份验证
• auth0-cli — 在终端中管理 Auth0 资源

快速参考

核心方法

方法	描述
createAuth0Client(options)	创建并初始化客户端（内部会调用 checkSession）
new Auth0Client(options)	实例化，但不自动检查会话
auth0.loginWithRedirect(options?)	重定向至 Auth0 Universal Login
auth0.loginWithPopup(options?)	在弹出窗口中打开 Auth0 登录
auth0.logout(options?)	清除会话并重定向
auth0.handleRedirectCallback(url?)	处理登录后的重定向结果
auth0.isAuthenticated()	Promise<boolean>
auth0.getUser()	Promise<User | undefined>
auth0.getTokenSilently(options?)	Promise<string> — 访问令牌
auth0.checkSession()	尝试静默重新进行身份验证

常见用例

• 登录/退出 → 参见上文第 4 步
• 保护内容 → 集成指南
• 使用令牌调用 API → 集成指南
• 刷新令牌 → 集成指南
• 组织 → 集成指南
• MFA 处理 → 集成指南
• 错误处理 → 集成指南

参考资料

• Auth0 SPA JS SDK 文档
• Auth0 Vanilla JS 快速入门
• SDK GitHub 仓库
• EXAMPLES.md — 高级模式
• API 文档