Clerk 登录复盘：Account Portal、Google One Tap 与 OAuth 客户端配置

9月 11, 2026

AI 参与说明（Agent：Grok）：本文由 Grok 根据 Clerk 官方文档、开源站点 tcitry-blog 已合并的公开 PR，以及 yindongliang.com 上已脱敏的生产排查结论整理与扩写。运行记录：模型 cursor-grok-4.6-high，执行入口 Cursor / Grok Bot；reasoning effort 与 CLI 版本未取得独立运行记录。官方 API 名称先经 Context7 检索 /clerk/clerk-docs（Context7 Pro），再对照 clerk.com 原始页面核对；扩写整理日期 2026-09-12。Clerk、Google Cloud OAuth 与 Account Portal 的选项可能变化，实施前请重新核对该日期之后的一手资料。本文不构成质量保证，也不代表作者本人执笔。

本次修订（2026-09-12，Agent：Cursor）：修正 One Tap 流程图节点 id click（Mermaid flowchart 的 interaction 保留字）导致无法渲染。运行记录：模型 cursor-grok-4.6，执行入口 Cursor Cloud Agent；reasoning effort 与 CLI 版本未取得独立运行记录。

本次修订（2026-09-16，Agent：Codex）：依据 Clerk 当前官方文档、固定版本源码与公开站点修复，补充普通登录、OAuth 和 Clerk 原生 modal / popup 的流程图，修正 Account Portal 首次注册能力与回跳方案的适用范围，记录同文档 hash 导航导致前端会话状态未恢复的问题。运行记录：模型 gpt-6-astra，reasoning effort ultra，执行入口 Codex Desktop，提供方 openai，CLI 0.154.0-alpha.6.2（不代表桌面 App 版本）。文档检索使用 Context7，并对照一手原文；源码机制、现场观察与未覆盖路径在正文中分别说明。

方案收敛修订（2026-09-16，Agent：Codex）：对照站点 e2f5882 更新当前接入方式：停用 GitHub，保留原有邮箱、密码、用户名与 Google；One Tap 恢复官方组件，删除站内认证续流程页。保留 /sso-callback/ 和旧兼容代码的历史分析，补充 One Tap 展示条件，并区分已部署状态与真实账号验证。运行记录：模型 gpt-6-astra，reasoning effort ultra，执行入口 Codex Desktop，提供方 openai，CLI 0.154.0-alpha.6.2。文档通过 Context7 检索并对照官方原文。

当前方案是：官方 Clerk modal 提供邮箱及 Google 登录入口，Google OAuth 使用原生 popup，Google One Tap 使用官方组件；必要的后续步骤交给 Clerk Account Portal。 本站已停用 GitHub 登录与注册，并删除 /sso-callback/ 页面。

本文保留此前 GitHub 与 /sso-callback/ 的排查过程，因为它揭示了一个可复用的区别：第三方授权、本站注册、Session 激活和页面显示已登录，是不同步骤。历史方案帮助解释故障；当前接入代码见第四节。

阅读前先认识这些词

中文名称用于词义对照；正文和图中固定使用左栏名称。

先说结论与版本范围

1. Account Portal 和嵌入站点的 Clerk 预构建组件都是官方方案。 前者把认证页面托管给 Clerk；后者由站点承载页面，Clerk 负责表单及认证流程。“原生”不应只用来指其中一种。
2. modal 和 OAuth popup 控制不同阶段。 mode="modal" 控制点登录后出现的界面，oauthFlow="popup" 控制之后的 OAuth 授权方式；它们可以同时使用。
3. /sso-callback/ 是本站曾配置的续流程地址，不是所有 Clerk 应用的必备页面。 原生 popup 允许后续流程导航父页面；当前由 Account Portal 承接，不再由本站提供该路由。
4. OAuth 成功、Session 有效与 React 状态就绪必须分别验证。 本次还发现一种带 hash 回跳的问题：Session 已存在，原页面却没有恢复已登录状态。
5. 普通 Google 与 Google One Tap 是两个入口。 两者均交给官方组件处理认证；旧 One Tap 方法包装和手写注册转移已删除。本站仍有 Astro UI 加载与导航集成，但不再维护自定义 OAuth 窗口协议。

当前站点实现以已部署提交 e2f5882 为准，依赖 @clerk/react 6.15.1。历史故障分析固定在 @clerk/shared 4.31.0、ClerkJS 6.31.0、UI 1.32.1，对应 2026-09-15 的线上取证与站点修复 8c795a3。这些历史运行时版本不代表读者现在浏览器中的版本。React 包会加载浏览器运行时，排障时应分别记录，不能只看 package.json。React SDK 加载实现

停用一个 social connection 不需要同时关闭邮箱、密码或用户名。本站在收敛方案时曾错误扩大了停用范围，随后已恢复原有配置；这属于配置范围错误，不是 Google 登录的技术要求。

一、没有 Clerk 时，正常登录做了什么

普通账号密码登录

以常见的服务端 Session 模型为例：后端校验用户提交的凭据，必要时要求额外验证，然后建立 Session。前端显示头像只是结果展示，受保护的数据请求仍由后端校验身份与权限。

flowchart TD
  form["用户提交账号与密码"] --> verify["认证后端校验凭据"]
  verify --> valid{"凭据有效？"}
  valid -->|否| retry["显示失败，允许重试"]
  valid -->|是| extra["完成必要的额外验证"]
  extra --> session["建立本站 Session"]
  session --> credential["浏览器保存会话凭证"]
  credential --> request["请求受保护的数据"]
  request --> authorize["后端校验身份与访问权限"]
  authorize --> result["返回获准访问的数据"]

图中省略了注册、找回密码和具体凭证存储方式；它解释的是“凭据校验 → Session → 业务授权”的分工。

使用 GitHub 的 OAuth 登录

换成 GitHub 登录后，应用不再接收用户的 GitHub 密码。以 GitHub 的 Web application flow 为例，浏览器去 GitHub 授权，GitHub 带 code 和 state 返回约定的 callback；认证后端校验流程、交换 token，并读取 GitHub 身份。将该身份关联到本站用户、创建新账户和建立本站 Session，是应用认证系统接下来的工作。 GitHub：Authorizing OAuth apps

flowchart TD
  entry["点击使用 GitHub 登录"] --> provider["浏览器进入 GitHub 授权页"]
  provider --> consent["用户登录 GitHub 并同意授权"]
  consent --> callback["GitHub 返回 code 与 state"]
  callback --> exchange["认证后端校验流程并交换 token"]
  exchange --> identity["读取 GitHub 身份"]
  identity --> match{"已有对应的本站用户？"}
  match -->|是| session["建立本站 Session"]
  match -->|否| signup["按本站规则完成注册"]
  signup --> session
  session --> original["返回原页面，加载获准访问的数据"]

OAuth 本身是授权协议。社交登录是在它提供的授权与身份信息之上完成应用登录；GitHub 账户、本站用户和本站 Session 不是同一个对象。图中“进入 GitHub”可以发生在当前页，也可以发生在 popup，这不会消除 callback 或注册步骤。

二、接入 Clerk 后，哪些工作由谁负责

Clerk 接管了身份关联、登录与注册状态、Session 管理以及预构建认证界面。应用仍需提供入口、正确的导航目标，并在业务后端校验权限。例如本站的评论由 Convex 保存，能显示 Clerk 用户菜单，并不单独证明该用户可以读取任意评论或私聊。

modal、OAuth popup 与 Account Portal

Account Portal 使用 Clerk 托管的预构建组件，支持登录、注册和账户管理。完全托管方案已经在本站测试过回访登录，并有一次新账户完成注册、返回原文章且保持登录的人工验证。因此，不能根据早期的某次 external_account_not_found，推导出 Account Portal 不支持首次注册。Account Portal overview

The modal is the entry UI; the popup carries the OAuth interaction.

在当前组件 API 中，mode="modal" 与 oauthFlow="popup" 是两个独立选项。前者打开页面内的对话框，后者选择 OAuth 的浏览器交互方式。<SignInButton />

官方 UI 在用户点击社交登录按钮时请求一个带尺寸的窗口，然后调用 authenticateWithPopup。浏览器最终可能显示小窗口、新 tab，或者阻止打开；popup 不保证固定的窗口外观。Firefox 中出现新 tab，不能单凭这一点判定站点已经改用整页 redirect。UI 1.32.1 源码、MDN：Window.open

这里必须区分“第一次打开的 OAuth 窗口被浏览器显示为 tab”与“已经出现 popup，随后又打开一个 callback tab”。后者是另一次导航或窗口行为，不能用浏览器对第一次 popup 的呈现方式来解释；应分别记录原页面、OAuth 窗口和新增页面的去向。

当前 Clerk 原生流程

下图只展开当前 Google OAuth 入口。邮箱登录在官方 modal 中处理；One Tap 是第六节说明的独立入口。popup 向父页面交接时，可能直接激活 Session，也可能需要继续认证。账户是否存在，并不是决定所有分支的唯一条件。

flowchart TD
  article["原文章：点击登录"] --> modal["Clerk modal：选择 Google"]
  modal --> popup["Clerk 打开 OAuth popup"]
  popup --> provider["第三方完成身份验证与授权"]
  provider --> callback["返回 Clerk callback"]
  callback --> reply{"popup 向父页面交接什么？"}
  reply -->|session| activate["父页面调用 setActive"]
  activate -->|无后续要求| ready["恢复已登录状态与原文章 URL"]
  reply -->|return_url| continuation["父页面进入 Clerk 托管续流程"]
  activate -->|需要完成 Session tasks| continuation
  continuation --> signup["完成必要的注册、验证或 Session tasks"]
  signup --> finish["Clerk 完成认证并返回原文章"]

这是对已核对的浏览器 SDK 协议的说明：收到 session 时，父页面刷新必要的 client 状态并调用 setActive；收到 return_url 时，父页面导航到该地址。Account Portal 内部针对每一种实例配置如何选出消息，不能仅凭客户端源码全部推断。ClerkJS 6.31.0：authenticateWithPopup

三、为什么 GitHub 新用户仍会进入 /sso-callback/

本节解释历史方案。 当时本站启用了 GitHub，并把 /sso-callback/ 配置为站内认证入口。当前 GitHub 已停用，该页面也已移除；以下保留旧版本的机制、页面职责与取舍，不是重新接入该路由的建议。

GitHub 已经认识这个人，不代表 Clerk 已经为本站创建好了 User 和 Session。 新身份可能需要从 SignIn 转到 SignUp，或者继续完成实例要求的字段、验证等步骤。即便最后无需用户再填表，流程本身也可能需要一次交接，不能把“页面跳转”直接理解成“必有字段缺失”。

更具体地说，历史版本 <SignIn /> 中的 GitHub 按钮先调用 signIn.authenticateWithPopup()；withSignUp 启用组合流程，并没有把按钮改成直接创建 SignUp。收到 return_url 后，父页面先导航到 callback，再由 Clerk 处理 transferable 状态并调用 signUp.create({ transfer: true })。这次创建可能立即完成，也可能需要补资料。因此，即使无需再填任何字段，也可能先跳转到父页面的 callback。SignIn attempt、官方 popup 回程注释、callback 中的注册转移

Clerk 的 <SignInButton> 文档明确说明：从 modal 发起 OAuth 后，如果需要转入注册，会导航到注册入口。如果没有单独配置 signUpUrl，但配置了站内相对 signInUrl，组合流程使用 signInUrl#/create。官方 modal 与注册转移说明

当时本站的 Provider 配置为 signInUrl="/sso-callback/"，没有单独设置 signUpUrl，因此续流程由该地址下的完整 <SignIn routing="hash" withSignUp oauthFlow="popup" /> 接管，URL 可能出现 #/create 或更深的内部路由。历史 Provider、历史 SsoCallback

这个页面是不是自定义的

页面外壳和 URL 属于应用，表单与认证流程属于 Clerk。 在这里引用的 8c795a3 版本中，页面没有自行交换 GitHub token，也没有另写一套普通 OAuth 的 postMessage、自动关闭或 transfer 状态机。它承载完整官方组件，让组件处理自己的 callback、注册续流程和 Session tasks。

不要混淆三个地址：

/sso-callback/ 只是本站当时使用的路由名；其职责是完整的认证续流程页。删除这个站内页面，不等于 OAuth 不再需要 callback：第三方仍要把结果交回 Clerk，只是应用不再自己承载后续页面。

能否把首次注册全部留在 popup

技术上可以设计这样的应用流程，但当前核对的 Clerk 原生组件没有提供一个“保证所有首次注册都留在 popup”的公开开关。 oauthFlow="popup" 也不作这个保证。原生流程允许 return_url 导航父页面；强行改写这条交接，就需要应用承担额外的窗口与认证流程协调。

把整个认证页面自行放入应用管理的子窗口，与“Clerk modal 内点击社交按钮，由 Clerk 打开原生 OAuth popup”是两种架构。前者还要处理窗口被阻止、注册未完成、取消操作、会话同步和窗口关闭，不能仅加一句 window.open() 就认为维护成本不变。

采用原生方式时，合理的预期是：尽量由 popup 完成普通 OAuth；需要继续注册时，允许进入完整官方组件，并最终回到原文章。 当前本站选择让 Account Portal 承接必要的后续页面，仍保留初始 modal。停用 GitHub 是本站减少支持范围的产品决定，不能据此推导出 Clerk 不支持 GitHub 新用户，也不能保证 Google 的每一种注册配置都不发生父页导航。

怎样区分正常续流程和故障

• 正常续流程：进入页面后继续注册、验证或自动完成，最终返回原文章且已登录。
• 需要排查：白屏、永久加载、反复进入同一地址、再次要求从头授权，或者完成后没有返回原文章。
• 仅看到 URL 还不够：不能据此断言一定缺 Username、邮箱未验证，或 Clerk 注册失败；需要查看当次的 SignIn / SignUp 状态和实际界面。

早期 external_account_not_found 反映的是当次登录尝试没有找到可用的 External Account。应检查是否允许转入注册，以及入口与 callback 是否承接同一流程。把 Username 改成 Optional 只会影响注册要求，不能替代从 SignIn 转到 SignUp；反过来，出现这个错误也不证明 Account Portal 本身不具备注册能力。<SignIn /> 的 withSignUp 与 transferable

四、当前接入方式：统一入口与完整官方组件

当前不再设置站内 signInUrl / signUpUrl，也不挂载 AuthContinuation。点击入口仍打开 modal；需要从 OAuth 转入注册时，Clerk 使用默认 Account Portal。采用这一配置的前提是 Account Portal 保持可用，且没有环境变量把入口覆盖回已删除的页面。Clerk 对 modal 转入注册的说明

下面是可放入已配置 Clerk 的 React 客户端项目中的精简示例，依赖 @clerk/react 6.15.1。AuthRoot 包住认证组件所在的 React 树，普通页面渲染 ArticleSignIn；clerk-navigation.ts 在第五节完整给出。登录方式由 Clerk 实例配置决定，前端不通过隐藏字段来停用认证方式。

import type { ReactNode } from 'react';
import { ClerkProvider, SignInButton } from '@clerk/react';
import { clerkRouterPush, clerkRouterReplace } from './clerk-navigation';

export function AuthRoot({ publishableKey, children }: {
  publishableKey: string;
  children: ReactNode;
}) {
  const currentPage = window.location.href;
  return (
    <ClerkProvider
      publishableKey={publishableKey}
      signInFallbackRedirectUrl={currentPage}
      signUpFallbackRedirectUrl={currentPage}
      afterSignOutUrl={currentPage}
      routerPush={clerkRouterPush}
      routerReplace={clerkRouterReplace}
    >
      {children}
    </ClerkProvider>
  );
}

export function ArticleSignIn() {
  const returnUrl = window.location.href;
  return (
    <SignInButton
      mode="modal"
      oauthFlow="popup"
      withSignUp
      forceRedirectUrl={returnUrl}
      signUpForceRedirectUrl={returnUrl}
    >
      <button type="button">Sign in</button>
    </SignInButton>
  );
}

返回地址使用完整 href，因此入口参数包含 /article/?source=login#comments 中的 query 和 hash。命令式 openSignIn 入口也使用相同选项，并显式传入 transferable: true。这是将转移能力交给 Clerk，不是在应用中执行 signUp.create()。当前共用 helper

当前流程已移除早期通过 sessionStorage 和全局监听强制恢复 URL 的方案。返回地址由入口参数、官方续流程和导航适配共同处理，不应继续叠加旧的跳转监听器争抢导航。

Astro 静态构建时的边界

上述示例读取 window，只能在浏览器中渲染。本站的认证 island 使用 client:only="react" 并提供静态 fallback。client:load 仍会先尝试服务端渲染；它不是“完全不执行 SSR”，因此曾在静态构建时触发 window is not defined。这是本站 Provider 的浏览器依赖带来的约束，不是说所有 Clerk React 组件都不能 SSR。历史 Astro 页面中的 SSR 修复

另一个仍保留的处理是多 island 的 Clerk 实例复用：不能只见到 window.Clerk.load 就认为 UI 已加载。当前 Provider 还检查 UI 组件是否已附着，避免把仅含加载入口的对象提前传给 <ClerkProvider Clerk={...}>，导致 modal 或 One Tap 无法渲染。这是该站点的加载集成，不会接管登录注册状态机。当前 Provider

五、另一个故障：Session 已建立，原文章仍在加载

现象与因果链

历史排查中，在带 query 和 #comments 的文章地址上重复观察到：GitHub OAuth 成功，原页面却持续等待认证；手动刷新后，用户菜单与需要登录的功能立即可用。这个对照把调查方向从“第三方是否授权成功”转到了“父页面有没有恢复 Session 状态”。

对 ClerkJS 6.31.0 的 setActive 与导航源码进行隔离验证后，得到以下链条：

flowchart TD
  activate["setActive 开始激活 Session"] --> transitional["暂时清空 session / user 并通知订阅者"]
  transitional --> navigate["默认 windowNavigate 发送 clerk:beforeunload"]
  navigate --> hash["目标是当前文档的 hash URL"]
  hash --> noUnload["浏览器没有真正卸载文档"]
  noUnload --> tracker["SDK 已把合成信号记作即将卸载"]
  tracker --> earlyReturn["setActive 提前返回，未恢复 Session 访问状态"]
  earlyReturn --> loading["React 持续等待；刷新后才恢复"]

这里的 clerk:beforeunload 是 SDK 自己发送的信号，不能与浏览器真正触发的 beforeunload 混为一谈。也不能把这个特定版本、特定回跳条件下的故障，扩大成所有 Clerk popup 都存在的问题。setActive 的过渡状态与提前返回、默认 windowNavigate、beforeUnloadTracker

Session existence and frontend readiness are separate observations.

Clerk.loaded 与 useAuth().isLoaded 不是同一个检查层次。脚本已经加载，仍可能在 Session 切换的过渡状态中；只延长加载超时，无法修复状态未恢复。

使用公开 router 接口修复

本站通过 <ClerkProvider> 的 routerPush / routerReplace 区分两种导航：

• 同文档：完整 URL 相同就直接返回；仅 hash 改变则执行普通 location.assign / location.replace，不制造 SDK 卸载信号。
• 跨文档：优先交给 Clerk 提供的 metadata.windowNavigate，保留 SDK 正常的导航语义。

下面的 clerk-navigation.ts 与上面的 React 示例配套。它没有调用内部 Session 恢复方法，也没有接管 OAuth 窗口通信。公开导航接口、SDK 导航分支

import type { ClerkProviderProps } from '@clerk/react';

type RouterFn = NonNullable<ClerkProviderProps['routerPush']>;

function navigateClerk(
  to: string,
  replace: boolean,
  metadata?: Parameters<RouterFn>[1],
) {
  const current = new URL(window.location.href);
  const destination = new URL(to, current);
  const sameDocument = destination.origin === current.origin
    && destination.pathname === current.pathname
    && destination.search === current.search;

  if (!sameDocument && metadata?.windowNavigate) {
    metadata.windowNavigate(destination);
    return;
  }
  if (destination.href === current.href) return;
  if (replace) window.location.replace(destination.href);
  else window.location.assign(destination.href);
}

export const clerkRouterPush: RouterFn = (to, metadata) =>
  navigateClerk(to, false, metadata);

export const clerkRouterReplace: RouterFn = (to, metadata) =>
  navigateClerk(to, true, metadata);

这是对该静态站点导航方式的适配。已由 React Router 等框架管理导航的应用，应先检查已有的 Clerk router 集成，不要不加判断地复制覆盖。输入来自 Clerk 的导航回调；如果另行接收用户提供的返回地址，还应按应用允许的目标校验，不能把这个函数当作任意 URL 的安全过滤器。

怎样复现和验证修复

公开仓库内的浏览器回归会启动本地 fixture，不需要真实 OAuth 账号或 Clerk 密钥。在已经安装项目依赖的 8c795a3 版本检出中执行：

npx playwright install chromium
npm run test:browser:clerk-navigation

测试实现见 tests/browser/clerk-navigation.mjs。预期结果包括：

最后一项是有意保留的旧行为对照：测试既要证明新实现满足预期，也应证明它确实覆盖了原来的失败条件。该浏览器测试直接验证导航行为；完整 setActive 的隔离执行验证和真实 OAuth 验收是另外两层证据，不能相互替代。

六、Google One Tap 是独立入口

普通 Google 按钮从 modal 发起 OAuth popup。Google One Tap 则使用 Google Identity Services 返回的 credential，再交给 Clerk 处理；两者的界面、触发条件与凭据路径不同，不能用其中一种登录成功代替另一种的验证。

两种 Google Cloud 白名单

Clerk 要求 Google One Tap 启用 Google social connection 并使用 custom credentials。Google 文档要求为网页集成配置正确的 JavaScript origin；如果使用 redirect endpoint 接收凭据，还要配置对应 redirect URI。具体要求取决于接入方式，不能泛化成“所有非 One Tap 的 Google 登录都只需要 redirect URI”。Clerk GoogleOneTap、Google：Get your Google API client ID

本站早期曾出现 401 invalid_client / no registered origin：Clerk social connection 和 callback 已配置，但发起 One Tap 的站点 origin 没有登记。补齐 origin 解决的是 Google 拒绝该网页来源的问题，不是 Clerk 注册续流程的问题。排查时应在实际使用的 OAuth client 中核对协议、域名和开发端口，而不是只看提示框是否能够出现。

旧兼容层已删除：当前使用官方组件

早期版本曾包装 authenticateWithGoogleOneTap 和 handleGoogleOneTapCallback，用收到的 token 尝试创建 SignUp，失败后再尝试 transfer。这段代码现已删除，也不应作为新项目的默认接入方式。旧实现，仅供历史追溯

当前仅挂载官方 <GoogleOneTap /> 并传入登录、注册完成后的返回地址。Clerk 官方组件本身支持 sign-in 和 sign-up；应用没有覆盖上述方法，也不自行创建账号、执行 transfer 或处理 OAuth 窗口通信。当前 One Tap 组件、Clerk GoogleOneTap

在第四节的 AuthRoot 内挂载以下组件，即可表达当前的认证接入；本站额外的 production 挂载条件在下一小节说明。

import { GoogleOneTap, useUser } from '@clerk/react';

export function ArticleOneTap() {
  const { isLoaded, isSignedIn } = useUser();
  if (!isLoaded || isSignedIn) return null;
  const returnUrl = window.location.href;
  return (
    <GoogleOneTap
      signInForceRedirectUrl={returnUrl}
      signUpForceRedirectUrl={returnUrl}
    />
  );
}

官方组件自身也会避免对已登录用户展示；这里保留的 useUser 判断是本站的挂载时机控制。当前仍需维护的集成是 UI 加载、返回地址和第五节的 router 适配。 其中带 hash 的导航修复有特定版本与静态站点背景，其他框架应先检查已有集成；这条适用范围仍值得保留，但它不属于 One Tap 注册补丁。

为什么刷新后仍看不到 One Tap

Mounting the component requests a prompt; it does not guarantee that the prompt will be displayed.

本站只在 production、使用 production publishable key、Clerk 已就绪且本站未登录时挂载 One Tap，没有额外等待秒数或刷新次数要求。同一浏览器已登录 Google 是常见前提，但不足以保证提示出现：

• 用户关闭过提示后可能进入 cooldown；反复刷新不会清除。非 FedCM 模式与启用 FedCM 时的策略不同，后者可由浏览器决定，不能给所有 Chrome 用户套用固定的两小时期限。
• Google 账号的登录提示偏好，或 Chrome 的“第三方登录”设置，可能禁止展示。
• 扩展或脚本加载失败也可能影响展示；Clerk 特别列出了 1Password 扩展的影响。Google One Tap 展示规则、Clerk 限制说明

排查时先区分“组件未挂载”“Google / 浏览器没有展示提示”和“已取得 credential 但认证失败”。前两种现象不能作为重新加入注册兼容层的依据。提示不可用时，用户仍可从正常登录按钮进入 modal。

七、按阶段排查，避免把所有问题都叫“登录失败”

八、验证结果能说明什么

验证记录需要带上方案版本，不能把历史成功用例移到新方案名下：

当前版本的部署确认不等于全部真实账号路径已验收。本次文档更新未新增 Google / 邮箱 / One Tap 的真实登录结论；Chrome 未显示 One Tap 的反馈也尚无确定原因。实际登录仍以“完成必要步骤、建立可用 Session、回到原页面”为成功标准。

最有复用价值的经验是：先分清入口界面、第三方授权、本站注册、Session 激活和业务访问，再决定该修哪一层。选择官方组件可以减少要自己维护的流程，但不会免除路由集成和浏览器边界的验证。

关于 Clerk 作为授权服务器时的机器身份，与这里的用户登录有何区别，可继续阅读 M2M 认证机制：通用原理与 Clerk M2M Tokens 实践。

一手资料与历史记录

本轮整理日期为 2026-09-16。本文链接到的 SDK 和站点实现固定版本；官方文档可能继续更新。

• Clerk Account Portal：Getting started
• Clerk SignInButton：入口与 OAuth flow
• Clerk SignIn：sign-in-or-up 与 Session tasks
• Clerk OAuth custom flow：注册转移与 missing requirements；使用预构建组件时，由组件处理这些状态，不应再并行安装一套手写 callback。
• 站点当前方案：保留邮箱并使用 Clerk 默认续流程
• 历史导航修复与站内续流程接入
• 早期入口与注册转移记录：PR #167、#169。早期 URL 存储兜底见 #171，仅作历史参考，当前实现已移除该路径。
• One Tap 早期排查记录：PR #176、#178；当前行为以本文固定版本源码为准。