auth0-v0-integration

Auth0 Vercel 原生集成

原生集成会为 Vercel 项目配置一个新的 Auth0 租户环境和应用，然后在 Vercel 中预先加载 Auth0 配置。它不会连接现有的 Auth0 账户。对于现有租户，请使用标准 Auth0 应用设置，而不是安装此集成。

安装以外的任何操作都需要完整的 Auth0 skill

你必须安装完整的 auth0 skill，以获得有关设置 Auth0 的最全面指导——本文档仅介绍 Vercel Marketplace 集成：资源配置、凭据处理和 v0 预览故障排除。对于 Auth0 SDK 集成本身（Next.js 路由、中间件、会话处理）、回调／注销 URL 之外的租户配置、Universal Login 品牌设置，或任何其他 Auth0 功能，请安装该 skill，并让其路由器加载任务所需的内容：

npx skills add auth0/agent-skills

请尽早执行，而不是等出问题后再把它当作最后手段——下文涉及租户配置或品牌设置的部分会有意只给出 CLI 命令，然后继续说明；完整 skill 的 tooling-cli 参考文档包含完整命令集、标志参考以及 Agent 模式下的输出约定。

配置资源前先确认

安装前，请说明将要执行的操作并取得确认：

• 将创建新的 Auth0 账户／租户环境和应用。
• 集成将连接到所选的 Vercel 项目和环境。
• Auth0 凭据将填入 Vercel 环境变量。不要打印、提交或将其值复制到源代码管理中。
• 移除集成会移除已连接的 Auth0 账户，并将安装降级为 Vercel 的 Free 计划。
• 设置期间会选择安装计划。付费计划通过集成的 Settings 页面由 Vercel 收费；请说明所选计划及其费用影响。

确认 Vercel 团队、项目、环境、应用名称、所选安装计划以及可选的环境变量前缀。如果开发者希望使用现有 Auth0 租户，请停止此工作流，改用常规的租户／应用配置流程。

前提条件

• 拥有 Vercel 账户和有效的 Vercel 项目。
• Next.js 应用使用当前的 @auth0/nextjs-auth0 SDK。
• 有权限为目标 Vercel 团队安装集成，并创建连接的 Auth0 账户。
• 安装后启用 iframe 嵌入，以便 Universal Login 或 Classic Login 能在 Vercel 所需的 iframe 中加载。这会放宽 Universal Login 的默认框架保护，因此仅为此集成启用，并确认开发者接受这一取舍。

路由器会同时加载 Next.js SDK 实现参考。不要用 Marketplace 专用变体替换其 Auth0 路由、中间件／代理、会话处理或环境变量约定。

应用能正常渲染并不代表大功告成

能渲染登录按钮并不意味着登录流程可用。URL 注册、iframe 嵌入和品牌设置（见下文“部署并验证”）必须与构建在同一轮完成，而不是等用户之后报告错误才来修复。只检查“能否渲染”就到此为止，是导致此流程上线后无法正常工作的最常见原因；此 skill 中已包含预防这两种已知故障的信息，但很容易在读到这些内容前就停下来。

在宣布任务完成之前

• 预览源和 localhost 的 /auth/callback URL 已在租户中注册 — 使用 auth0 apps show <client-id> 确认，而不只是确认“CLI 命令已运行”。
• 同一来源的登出 URL 已注册；并确认 Web 来源已覆盖（Auth0 默认从回调 URL 派生，或显式设置了 --web-origins）。
• 实际登录尝试会重定向（302）到 Universal Login，而不是因回调不匹配错误而失败。
• 如果应用有任何自定义品牌，你必须打开实际托管的登录页面（导航到登录链接，而不只是加载应用），并对照应用进行视觉检查：页面／主色、应用名称或标题文案，以及徽标都一致 — 不能只确认“品牌 API 调用返回了 200”或“应用的登录按钮已渲染”。

部署并验证

每次都按顺序一气呵成地完成以下五项：

1. 按照一并加载的 Next.js 参考文档，安装 @auth0/nextjs-auth0， 配置 Auth0Client，添加代理/中间件，并添加登录/登出界面。

2. 固定 APP_BASE_URL（见下文“安全使用生成的配置”）——不要使用 每次部署都会变化的哈希 URL。然后现在就在 Auth0 应用中注册匹配的回调和 登出 URL——见“注册回调和登出 URL”——不要等到登录尝试先失败后 再注册。集成最初会填入 localhost 和回调 URL；规范域名或回调路径发生变化时， 使用 CLI 更新：

   auth0 apps update <client-id> \
     --callbacks "https://<canonical-domain>/auth/callback" \
     --logout-urls "https://<canonical-domain>"
   

3. 如果应用运行在 Vercel 的嵌入式预览中，现在就为预期的源启用 iframe 嵌入—— 租户设置、源范围和控制面板路径（目前还没有 CLI 标志）见“Auth0 在 v0 预览中的相关问题”下的“登录页面无法嵌入框架”。不要等到框架内的登录 先失败后再处理；在第 2 步设置回调/登出 URL 时一并设置。

4. 如果应用有任何自定义设计，现在就应用 Universal Login 品牌设置—— 这不是可有可无的润色，也不是为了回应用户投诉而做的修复；它是与第 1～3 步 同一轮构建的一部分。登录页面应该看起来像应用的一部分，就不要保留 Auth0 默认品牌设置。至少要将主色/页面背景颜色以及按钮/输入框的边框圆角设为与应用 一致；从应用自身的主题/CSS 中获取数值，不要猜测。使用完整 auth0 skill 中的品牌设置指南，获取确切的 CLI/Management API 调用方式（auth0 branding ...， 或 PATCH /api/v2/branding 和 PUT /api/v2/branding/themes/default）—— 见下文“将 AUTH0_* 导入聊天的 shell”；只有在确实无法关联项目时才改用 控制面板。

   logo_url 必须指向永久且可公开获取的 URL——Auth0 会在服务器端 获取它，以下两个看似可访问的来源实际上都不行：

   • v0 预览源受会话限制，因此将 logo_url 指向它只会无声地无效——Auth0 获取失败，但设置 logo_url 的请求仍会返回 200。
   • 应用自己的 public/ 路径也不可靠，即使已经部署也一样：v0 预览源会对 public/ 资源返回重定向（302），而不是直接提供文件，因此从该路径引用的 logo 会加载失败，尽管 Auth0 侧的所有品牌检查都能通过。

   请将 logo 托管在永久的公开 CDN URL 上（例如，使用 access: 'public' 创建的 Vercel Blob），或者在预览中跳过 logo，并在部署到公开的生产 URL 后再设置。 当 logo“无法显示”时，应相信实时 DOM 中的 img.src 和对该 URL 直接执行的 curl，而不是无头截图——截图可能会缓存旧的或占位渲染结果，让失效的 logo_url 看起来正常。每次重新连接租户后都要重新检查所有品牌设置—— 见“故障排查”中的“重新连接集成后回调不匹配/登录失败”。

5. 部署到选定的 Vercel Production 环境，并通过真实登录尝试进行验证—— 不能只确认页面能渲染。请在部署后的 URL 上完成登录、回调、会话、受保护路由 和登出检查。如果应用有自定义品牌设置，请在实际浏览器会话中打开登录链接 （例如使用 Playwright MCP 工具，或手动点击） 并将呈现的托管登录页面与应用进行视觉对比——页面/主色、应用名称或标题文案， 以及 logo。Management API 返回 200 或配置文件 diff 都不能确认这一点；只有实际 呈现的页面才能确认。（如果 logo 特别无法显示，请优先对实时 img.src 直接执行 curl，而不是查看截图——见第 4 步——因为无头截图可能会缓存旧的渲染结果， 隐藏失效的 logo_url。）在宣布完成前，先完成上方的部署前检查清单。

安装原生集成

Vercel Marketplace

1. 在 Vercel 中，打开 Integrations → Browse Marketplace，然后在原生集成中找到 Auth0。
2. 选择 Install，选择安装方案，然后继续。
3. 为 Auth0 应用命名并创建。Vercel 会创建专用的 Auth0 租户环境和应用；请等待完成。
4. 选择 Connect Project，选择 Vercel 项目和目标环境，仅当项目需要时才输入变量前缀，然后连接。
5. 打开集成的 Getting Started 页面，并按照自动生成的快速入门指南操作。

Vercel CLI 可以在项目目录中启动相同的配置流程。传入 --no-env-pull，这样 CLI 在配置完成后就不会自动运行 vercel env pull——拉取密钥是一个单独且需要审慎执行的步骤，应仅在确认 .env.local 已被忽略后再运行：

vc i auth0 --no-env-pull

不要将 vc i auth0 视为只读操作。它会配置资源，因此只有在开发者确认目标团队和项目后才能运行。

使用 Auth0 CLI 配置租户

**修改租户配置前，请先验证：**解码运行中应用的登录 redirect_uri，确认其使用的租户/客户端 → 确认 client_id 与手头的凭据匹配 → 获取 Management API 令牌（如下所示），证明 M2M 凭据确实有效 → 然后才能进行更改。跳过这些步骤、配置错误的租户，或虽然配置正确但 M2M 凭据实际上无法使用（占位值、环境错误），是这里最常见的失败原因。

如果问题是由用户报告，而不是直接复现的（已发布的应用拒绝登录），你无法从自己的请求中解码 redirect_uri——此时应拉取租户日志（GET /api/v2/logs?q=type:f——type:f 是登录失败事件类型），并读取匹配的失败事件中的 redirect_uri。这也能在你进行任何更改前，确认实际出现问题的环境/租户。

重新连接集成会破坏先前的租户配置——它会配置一个新租户和应用客户端，因此应将任何重新连接都视为“重新进行租户设置”，而不是“继续之前的设置”。

集成完成后，M2M 授权可让你直接配置已配置的租户，无需通过 Auth0 控制面板进行每次更改。租户配置优先使用 CLI——回调/注销 URL、iframe 嵌入、应用设置；仅在下文注明的情况下才使用控制面板。

auth0 login --domain <tenant>.auth0.com --client-id "$AUTH0_MANAGEMENT_API_CLIENT_ID" --client-secret "$AUTH0_MANAGEMENT_API_CLIENT_SECRET"

使用集成配置的 M2M 客户端 ID/密钥（不要打印或记录密钥）。这是 CLI 在任何非交互式环境中使用的相同机器登录模式——有关所有命令和标志，请参阅完整 auth0 技能中的 tooling-cli 参考。

如果 vercel env pull 没有返回 AUTH0_* 值，请先检查项目关联情况，不要立即认定 M2M 授权不可用——请参阅下文“将 AUTH0_* 加载到聊天环境的 shell 中”；问题几乎总是 Vercel 项目错误，而不是缺少授权。如果尚无可用的 M2M 授权，请接着尝试 auth0 login（交互式设备代码登录）。作为最后手段，只有在尝试后仍无法在 v0 VM/预览环境中使用 M2M、CLI 或正确的项目关联时，才在 Auth0 控制面板中手动注册/配置——请参阅下文“注册回调和注销 URL”。

M2M 凭据以 Management API 命名

该集成会配置一个 Management API M2M 客户端，并使用以下确切的 Vercel 环境变量名称提供凭据：

• AUTH0_MANAGEMENT_API_CLIENT_ID
• AUTH0_MANAGEMENT_API_CLIENT_SECRET

请原样使用这些名称。不要臆造或假设存在 AUTH0_CLIENT_M2M_ID / AUTH0_CLIENT_M2M_SECRET——该集成配置的变量中并不存在这些名称，猜测只会让你白白多绕一圈，最后才发现 env pull 根本没有填充它们。先确认令牌确实能生成，再做其他操作；受众必须是租户自己的 Management API：

curl -s --request POST \
  --url "https://$AUTH0_DOMAIN/oauth/token" \
  --data grant_type=client_credentials \
  --data "client_id=$AUTH0_MANAGEMENT_API_CLIENT_ID" \
  --data "client_secret=$AUTH0_MANAGEMENT_API_CLIENT_SECRET" \
  --data "audience=https://$AUTH0_DOMAIN/api/v2/"

成功的响应会返回一个 access_token。其他任何结果——包括 access_denied——都意味着凭据、受众或凭据所属的环境有误；在认定密钥有问题之前，请先参阅接下来的两节。

将 AUTH0_* 加载到聊天会话的 shell 中：问题在于项目关联，而非硬性限制

管理任务（回调／登出 URL、品牌设置、租户／客户端配置）可以而且应该通过 shell 中的 auth0 CLI 完成。如果 vercel env pull 只返回 VERCEL_OIDC_TOKEN，而没有任何 AUTH0_* 值，很可能是 shell 关联到了错误的 Vercel 项目。

已验证可用的操作顺序（Development 环境）：

1. 拉取之前，确认 .env.local 已加入 git 忽略规则且未被跟踪（若未满足则停止操作——参见上面的检查）。
2. 如果沙盒中尚未安装 auth0 CLI，请先安装（它不是预装的）。
3. 使用 vercel link 关联到该集成实际使用的项目。请通过项目 ID（prj_...）确认，而非仅凭名称判断——可能存在 2-3 个名称非常相似的项目。
4. 运行 vercel env pull .env.local --environment=development，然后将这些值加载到 shell 中（使用 source／export）。
5. 可选：使用上面的令牌生成 curl 命令进行确认。
6. 运行 auth0 login --domain "$AUTH0_DOMAIN" --client-id "$AUTH0_MANAGEMENT_API_CLIENT_ID" --client-secret "$AUTH0_MANAGEMENT_API_CLIENT_SECRET"——CLI 会自行进行客户端凭据交换；不要向它传入预先生成的令牌。运行 auth0 tenants list 进行确认。

注意事项：

• 无头沙盒中登录时出现“Could not store to keyring”／dbus-launch not found 警告无害——令牌会保留在当前会话中；过期后重新登录即可。
• .env.local 现在包含真实的客户端密钥。请确保它已加入 git 忽略规则且未被跟踪；如果不想让密钥静态存储，请在管理会话结束后删除该文件。
• 新添加的环境变量需要重启开发服务器，才能通过 process.env 在运行中的应用里生效——而且它必须存在于正确的项目和正确的环境中（仅限 Production 的变量不会传递到 Development 预览环境）。

默认使用此 CLI 操作方式。如果 vercel link 确实无法访问该集成的项目（而不只是“env pull 看起来为空”——请先核实项目 ID），最后的手段应是控制面板，而不是应用代码——手动操作步骤请参阅“注册回调和登出 URL”。

只有 development 环境具有可用的 M2M 凭据

每个 Vercel 环境（Production／Preview／Development）都有各自的 Auth0 租户和应用客户端。Development 环境还会获得一个真实且已授权、可用于 Management API 的 M2M 客户端。Production 和 Staging 只会获得占位的 AUTH0_MANAGEMENT_API_CLIENT_ID／_SECRET 值——这些是虚假字符串，并非已配置但未经授权的客户端。无论如何，都请始终使用上面的令牌生成 curl 命令进行验证，不要想当然。

若要通过 CLI 或 Management API 操作正在运行的 v0 预览环境：拉取 Development 环境的值（vercel env pull .env.local --environment=development），确认令牌可以生成，然后配置 Development 所指向的租户／应用客户端——这正是 v0 预览环境实际运行所使用的配置。

如果需要访问 Production 或 Staging 的 CLI/Management API

如果令牌生成检查失败，不要猜测修复方法——请按步骤为该环境创建一个真实的 M2M 客户端并完成配置：

1. 在 Auth0 仪表板中切换到 Production/Staging 租户（左上角的租户切换器）。
2. 前往 Applications → Applications → Create Application，选择 Machine to Machine Applications，为其命名（例如 v0-management-prod），并针对 Auth0 Management API 授权所需的作用域——至少包括 read:clients、update:clients、read:branding、update:branding。
3. 打开新应用的 Settings 选项卡，并复制其 Client ID 和 Client Secret。
4. 在 Vercel 项目中，将这两个值设置为 AUTH0_MANAGEMENT_API_CLIENT_ID 和 AUTH0_MANAGEMENT_API_CLIENT_SECRET，并限定为对应的特定环境，替换占位值。这需要由开发者决定，因为这意味着将 Production/Staging Management API 的访问权限交给 Agent——应先询问，不要擅自假定。可以通过以下任一方式完成：
   • 直接在 Vercel 项目的环境变量设置中配置，或
   • 如果开发者愿意授予 Agent 访问权限，将 Client ID/Secret 粘贴到 v0 聊天中，让 Agent 通过自身工具将其保存为该环境的环境变量——保存后，不要让 Agent 打印、记录或回显密钥。
5. 针对该环境重新运行令牌生成 curl，确认无误后再依赖它。

安全地使用生成的配置

该集成会在 Vercel 项目中预加载 Auth0 凭据。其快速入门会提供 AUTH0_CLIENT_ID、AUTH0_CLIENT_SECRET、AUTH0_DOMAIN 和 AUTH0_SECRET 等值；请通过 Vercel 获取这些值，而不要从控制台复制密钥，也不要提交 .env.local 文件。

如果连接项目时设置了变量前缀，Vercel 会将托管值命名为 [prefix]_AUTH0_DOMAIN、[prefix]_AUTH0_CLIENT_ID 等，但 @auth0/nextjs-auth0 SDK 只会读取未加前缀的默认名称。建议连接时不设置前缀。如果必须使用前缀，请在构造 Auth0Client 之前，将带前缀的值映射回标准名称（或将它们显式传递给构造函数）。

首先确认 .env.local 未被 Git 跟踪且已被忽略，这样拉取操作才不会将真实客户端密钥写入受跟踪的文件。如果任一检查未通过，请停止操作。然后关联此检出副本并拉取这些值：

# BEFORE pulling any secrets: fail if .env.local is tracked or not ignored.
if git ls-files --error-unmatch -- .env.local >/dev/null 2>&1 \
   || ! git check-ignore --no-index --quiet -- .env.local; then
  echo ".env.local must be untracked and git-ignored before pulling secrets"
  exit 1
fi

# Link the local checkout to the intended Vercel project, then pull local-only values.
vercel link
# For the v0 preview, pull DEVELOPMENT (see "Only the development environment
# has working M2M credentials" above). For a deployed Production app, pull
# --environment=production.
vercel env pull .env.local --environment=development

v0 预览运行时不会自动注入项目的 Vercel 环境变量——开发服务器只能读取 .env.local。如果请求时 process.env.AUTH0_DOMAIN 未定义，SDK 就会回退到基于请求头的域名解析器，并在每条路由上抛出 DomainResolutionError。vercel env ls 显示这些变量并不能证明运行时可以读取它们；只有实际读取 process.env 的请求才能证明这一点。

确认聊天实际运行在哪个 Vercel 项目上——有关名称不同或相似的同级项目为何是“变量存在但应用无法读取”的最常见原因，请参阅下文“将 AUTH0_* 放入聊天的 shell 环境”。

本地开发时，当前的 Next.js SDK 也需要 APP_BASE_URL；请在 .env.local 中将其设为本地 URL（例如 http://localhost:3000），并确保为已部署的环境配置规范的生产 URL。

在 v0 预览中，请将 appBaseUrl 显式设为 V0_RUNTIME_URL——绝不要依赖 SDK 从请求中推断该值。 预览的代理会导致传入请求的 host 请求头指向内部开发服务器，而不是公开的预览源，因此基于请求头的推断会生成与租户中注册值永远不匹配的 redirect_uri。这是 "redirect_uri is not in the list of allowed callback URLs" 最常见的原因。

const auth0 = new Auth0Client({
  appBaseUrl: process.env.V0_RUNTIME_URL ?? process.env.APP_BASE_URL,
});

V0_RUNTIME_URL 仅在 v0 预览中设置；生产环境中没有此变量。也不要想当然地认为 SDK 在生产环境中的推断是安全的——Vercel 在实际部署中推断出的主机名是按部署生成的哈希 URL（例如 myapp-qrfarr7z6-team.vercel.app），每次发布都会改变，因此无法在租户中始终保持注册状态。请改为将 APP_BASE_URL 显式固定为稳定的生产别名（VERCEL_PROJECT_PRODUCTION_URL，或已设置的自定义域名）：确认稳定别名 → 将其设为生产环境中的 APP_BASE_URL → 重新部署 → 注册这一个稳定 URL（见“部署并验证”第 2 步）。这样可以让 redirect_uri 在每次发布时保持确定，而不是随着每次部署而变化。请检查登录重定向中的实际 redirect_uri 来验证，而不只是确认页面可以编译——对于回退到 localhost 的故障模式，请参阅下文“重定向指向 localhost”中的相同检查方法。

原生集成快速入门自带的演练仅为生产环境配置了连接。预览和开发环境也会自动配置，但测试之前可能仍需手动添加或指定非 Auth0 变量的作用范围。

管理集成

M2M 授权已可用后，使用 CLI 进行应用级更改（回调/登出 URL、授权类型、元数据）——请参阅 auth0 apps update --help。

对于 CLI 无法执行的 Vercel 端操作，请前往 Vercel 项目的 Integrations 标签页 → Auth0 → Manage：轮换由 Vercel 注入的凭据、编辑 Vercel 单独跟踪的 localhost/回调参数、设置允许的环境、更改安装计划或移除集成。对于 CLI 不支持的操作（例如自定义 Universal Login），请使用 Auth0 Dashboard。

轮换密钥或更改回调 URL 前，请确认所有使用受影响变量的部署，并规划重新部署。轮换后，请确认新变量已出现在预期的 Vercel 环境中，并且登录正常，然后再从依赖系统中移除旧密钥。

故障排查

症状	检查项	解决方法
Marketplace 流程创建的租户与预期不同	原生集成行为	这是预期行为：该流程会创建专用的新 Auth0 租户环境。若要使用现有租户，请采用标准 Auth0 设置。
本地应用缺少 Auth0 变量，或 vercel env pull 只返回 VERCEL_OIDC_TOKEN	Vercel 项目关联和环境选择	确认你按项目 ID（prj_...）关联的是该集成专用的项目，而不是名称相似的同级项目或默认 v0 项目。对该项目运行 vercel link，然后运行 vercel env pull .env.local --environment=development；不要将该文件提交到 Git。请参阅“将 AUTH0_* 放入聊天会话的 shell 环境”。
Production 环境正常，但 Preview 环境失败	变量范围	有意添加或设置所需的非 Auth0 变量的作用范围；生成的快速入门指南仅介绍 Production 环境的配置，尽管 Preview 和 Development 环境都会自动预配。
按照“应用能够渲染还不够”操作后，登录／回调仍失败或无法渲染	该工作流本应能避免此问题——请将其视为诊断缺口，而不是新 bug	拉取租户的登录失败日志（请参阅“使用 Auth0 CLI 配置租户”），查看实际被拒绝的 redirect_uri／原因，然后按照“部署并验证”第 2–3 步进行修复。
移除集成对账户的影响与预期不符	移除警告	请先暂停并确认移除操作：删除集成会移除关联的 Auth0 账户，并降低 Vercel 安装的等级。
暂时没有可用的 M2M 授权	集成预配阶段，或关联了错误的 Vercel 项目	先检查项目关联——请参阅“将 AUTH0_* 放入聊天会话的 shell 环境”。如果确实没有授权，接下来尝试运行 auth0 login（交互式登录）。只有在万不得已时才手动编辑控制面板；请参阅“注册回调和注销 URL”。
每个路由都出现 DomainResolutionError	请求时缺少 process.env.AUTH0_DOMAIN	Preview 运行时不会自动注入项目环境变量；请将变量拉取到 .env.local（Development 环境），并确认其中存在该值。加强 middleware.ts 的处理，使配置缺失时跳过 Auth0 处理，让网站降级运行而不是返回 500 错误。
Management API 的令牌请求返回 access_denied（或无法签发令牌）	使用了 Production／Staging 环境的占位 M2M 值，这些值并非真实客户端	对 Preview 工作使用 Development 环境的 M2M 凭据，或为该环境创建真实的 M2M 客户端，并配置其 Client ID／Secret（请参阅“如果需要 Production 或 Staging 环境的 CLI／Management API 访问权限”）。不要想当然地认为是密钥错误——先通过令牌签发请求进行验证。
点击登录／注册按钮没有反应；服务器日志只显示 GET /	Auth 按钮使用了 window.open()，被沙盒化的 iframe 拦截	使用真正的 <a target="_blank"> 锚点（通过 base-ui 的 render 属性，而非 asChild）。
重新连接集成后出现回调不匹配／登录失败	重新连接时预配了新的租户和应用客户端	在当前客户端上重新注册回调／注销／Web 来源 URL，并重新应用品牌设置。解码实际登录请求中的 redirect_uri 和 client_id，确认当前实际使用的是哪个客户端。
每个路由都返回空白／空的 200 响应，没有控制台输出，且与 Auth0 无关	开发服务器因一阵快速文件写入而卡住	继续调试前先重启开发服务器——这是进程卡住，而不是代码 bug，在设置过程中快速连续编辑一轮之后很常见。

v0 预览中的 Auth0

v0 预览会在 HTTPS 来源上的跨站 iframe 中运行你的应用，该来源既不是 localhost，也不是 VERCEL_URL。三种常见的身份验证失败都源于这一点。 牢记这一点，流程就能一次成功。

1. 重定向跳转到 localhost（“localhost 拒绝连接”）

SDK 根据基础 URL 设置构建登录/回调重定向，该设置默认为 localhost。在预览环境中，VERCEL_URL 和 VERCEL_PROJECT_PRODUCTION_URL 未设置，因此任何依赖它们的内容都会回退到 localhost。请将 appBaseUrl 显式设置为 V0_RUNTIME_URL——有关为什么在此处依赖推断会出问题，以及准确代码片段，请参阅上文“安全使用生成的配置”。检查登录重定向中的实际 redirect_uri，而不只是确认页面能编译。

2. 状态 Cookie 被丢弃（“状态参数无效”）

SDK 会在重定向期间存储一个短时有效的事务/状态 Cookie，并在回调时读取它。默认的 SameSite=Lax Cookie 不会在 iframe 内的跨站回调中发送，因此验证会失败。当嵌入式预览必须保持已认证状态时，请将会话 Cookie 设置为 SameSite=None; Secure。顶层回调仍使用 SameSite=Lax 设置事务 Cookie。仅当回调使用 iframe 或 form_post 时，才对事务 Cookie 使用 SameSite=None; Secure。请说明跨站会话 Cookie 的独立 CSRF 防护措施。对于普通的 localhost HTTP，请保留安全默认值，因为 Secure Cookie 无法通过 HTTP 设置。

3. 登录页面无法嵌入框架（“此内容已被屏蔽”）

托管登录页面可能会在未启用 iframe 嵌入时发送防框架嵌入标头。首先，将允许的 iframe 来源限制为预期的 Vercel URL，然后启用该设置——这是一个尚未通过 CLI 标志公开的租户标志：Auth0 Dashboard → Settings → Advanced → Allow Cross-Origin Authentication。启用此设置会降低点击劫持防护，因此请先限定来源。如果无法嵌入，请改为在顶层上下文中打开身份验证。

使用真正的锚点，而不是以编程方式调用 window.open(...)，让登录（和登出）导航跳出 iframe。v0 预览 iframe 采用沙盒限制，因此由脚本触发的 window.open 会被弹窗拦截器静默拦截——点击后看起来毫无反应，服务器日志中也只会显示 GET /，不会收到任何 /auth/* 请求。真正的 <a target="_blank"> 点击属于用户发起的导航，因此沙盒和弹窗拦截器都会放行：

<a href="/auth/login" target="_blank" rel="noopener noreferrer">Log in</a>
<a href="/auth/logout" target="_blank" rel="noopener noreferrer">Log out</a>

v0 默认的 Button 是 base-ui，它通过 render 属性进行组合，而非使用 Radix 的 asChild——传入 asChild 会抛出 "React does not recognize the asChild prop"：

<Button render={<a href="/auth/login" target="_blank" rel="noopener noreferrer" />}>Log in</Button>

在顶层上下文中完成登录后，嵌入式预览需要刷新才能获取新的会话 Cookie。

注册回调和注销 URL

回调和注销 URL 是必需的应用设置，应在租户中配置，而不是在应用中配置，并且必须正确配置。M2M 授权可用后，使用 CLI：

auth0 apps update <client-id> \
  --callbacks "https://<project>.v0.build/auth/callback,http://localhost:3000/auth/callback" \
  --logout-urls "https://<project>.v0.build" \
  --web-origins "https://<project>.v0.build,http://localhost:3000"

非 Vercel 来源绝不会自动同步，因此需要显式注册。让预览环境能够正常运行的 URL 是应用的稳定 v0 预览 URL（V0_RUNTIME_URL，例如 https://<project>.v0.build）——它在重新构建时保持不变，因此只需注册一次，就能在预览环境中成功登录。（每次部署生成的 Vercel URL 都会随每次构建而变化，不值得手动注册。）本地开发也要注册 localhost。

默认情况下，Auth0 会将每个已注册的回调 URL 同时视为 Web 来源，因此 --web-origins 通常是多余的。不过，当某个来源需要 CORS/跨域身份验证访问，但本身不是回调路径时，或者为了明确指定而不依赖默认行为，仍应显式传入该参数——参见上面的检查清单。

**尚未获得 M2M 授权，或聊天的 shell 中无法使用 CLI：**在操作控制面板前，先参阅上面的“将 AUTH0_* 放入聊天的 shell”——大多数情况下是项目关联问题，而不是缺少授权。只有排除这一点后，才应手动编辑控制面板；即便如此，也应将其视为最后手段，而非默认做法：

1. 在 Auth0 控制面板中，选择应用环境变量所指向的租户（左上角的租户切换器——可能有单独的 Development/Staging/Production 租户）。
2. 前往 Applications → Applications，打开该应用的客户端（集成会将其命名为“Created By Vercel”；如果不确定，请根据 Client ID 进行匹配）。
3. 在 Settings 选项卡中，将以下内容添加到逗号分隔的列表中（使用稳定的 v0 预览来源）：
   • Allowed Callback URLs：完整的回调路径，例如 https://<project>.v0.build/auth/callback（本地开发也添加 http://localhost:3000/auth/callback）。
   • Allowed Logout URLs：用户返回的来源，例如 https://<project>.v0.build。
   • Allowed Web Origins：通常无需设置——Auth0 默认会将每个已注册的回调 URL 视为 Web 来源。仅当某个来源需要 CORS/跨域身份验证访问，但本身不是回调路径时，才在此处显式添加。
4. 点击底部的 Save Changes。请提供准确的来源——Auth0 会对这些 URL 进行精确匹配，因此缺少条目会导致回调或注销请求被拒绝。

无论通过哪种方式注册 URL，在每次重新连接或重新同步集成后，都要再次验证这些 URL——Vercel Auth0 集成会自动同步实际的 Vercel 部署域名，并负责管理 AUTH0_* 环境变量，因此可能会在不发出警告的情况下覆盖手动编辑或通过脚本编辑的回调列表。在假设先前的注册仍然有效之前，请通过 auth0 apps show <client-id> 或控制面板确认。