跳转到内容
Jason's Study

Clerk — 把登录注册组织 MFA 整套外包给云的 SaaS 认证 SDK

是什么

Clerk 是一套把”登录、注册、用户资料、组织、邀请、多因素认证”整套外包给云的认证基础设施。日常类比：像点外卖——你不用自己买菜、切菜、炒菜，下单 5 分钟就能吃；同理你不用自己建用户表、写 OAuth 回调、画登录页，5 行代码就能拥有完整的认证系统。

你写：

<ClerkProvider>
  <SignIn />
</ClerkProvider>

页面上立刻渲染出一个和 Linear / Vercel 同款的登录卡片——支持邮箱、密码、Google、GitHub、passkey、MFA。后台用户表、session、JWT 签发全部跑在 Clerk 云上，你的应用只是”接线工”。

这种打法是过去几年 B2B SaaS（Linear / Cal.com / Vercel 自家）的事实标准。

为什么重要

不理解 Clerk，下面这些事都没法解释：

  • 为什么 2024 年的 React/Next.js 项目能”5 分钟接入认证”，而 Auth0 时代要做 1-2 天
  • 为什么同样是 auth，auth-js / better-auth / lucia 是 OSS library，Clerk 却是 SaaS——商业模式的根本分叉
  • 为什么 Clerk 的 middleware 能跑在 Vercel Edge runtime，而老牌 jsonwebtoken 包不能
  • 为什么 B2B 客户愿意为”组织 + SAML + passkey 一站式”付 $0.02/MAU

核心要点

Clerk 的设计可以拆成 三层：

  1. 接线 SDK（开源 MIT）：@clerk/nextjs @clerk/react @clerk/backend 等 22 个 npm 包。日常类比：餐厅的”外卖小哥”——他不做饭，只把云端做好的东西送到你应用门口。SDK 本身不实现任何 auth 逻辑。

  2. SaaS 云（闭源）：FAPI（前端 API，浏览器直连）/ BAPI（后端 API，server-to-server）/ JWKS（公钥分发）三个端点。用户表、密码哈希、session、组织都在 Clerk 数据库里——你看不见。

  3. Prebuilt UI 组件（核心卖点）：<SignIn /> <UserButton /> <UserProfile /> <OrganizationSwitcher /> 直接渲染在你的域名下，不是被踢去 auth0.com 那种统一登录页。这一点是它和 Auth0 拉开差距的关键。

三层加起来叫”drop-in auth”——开发者只关心接线，不关心 auth 本身。

实践案例

案例 1：Next.js 项目 5 分钟接入

app/layout.tsx
import { ClerkProvider } from '@clerk/nextjs'
export default function Root({ children }) {
  return <ClerkProvider><html><body>{children}</body></html></ClerkProvider>
}


// middleware.ts
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'
const isProtected = createRouteMatcher(['/dashboard(.*)'])
export default clerkMiddleware(async (auth, req) => {
  if (isProtected(req)) await auth.protect()
})


// app/sign-in/[[...sign-in]]/page.tsx
import { SignIn } from '@clerk/nextjs'
export default () => <SignIn />

填邮箱、收 OTP、回 dashboard，所有用户管理你都没碰。这就是核心卖点。

案例 2：在 Edge runtime 校验 JWT

Next.js middleware 跑在 Vercel Edge（V8 isolate，没 Node crypto），原生 jsonwebtoken 不能用。Clerk 直接用 Web Crypto subtle.verify：

const cryptoKey = await crypto.subtle.importKey('jwk', jwks, alg, false, ['verify'])
const ok = await crypto.subtle.verify('RSASSA-PKCS1-v1_5', cryptoKey, sig, data)

一份代码同时跑在 Node / Bun / Deno / Cloudflare Workers / Vercel Edge。这是 Clerk 比 auth-js 早一年做到的事。

案例 3：B2B 多组织 + RBAC

import { OrganizationSwitcher, useAuth } from '@clerk/nextjs'


function Toolbar() {
  const { has } = useAuth()
  return (
    <>
      <OrganizationSwitcher />
      {has({ role: 'admin' }) && <button>Invite member</button>}
    </>
  )
}

<OrganizationSwitcher /> 自带”创建组织 / 切组织 / 邀请成员 / 改角色”完整流程；auth().has({ role: 'admin' }) 直接读 JWT 里的 org_role claim。B2B SaaS 三天的活儿压缩到 30 分钟——这是 Linear、Cal.com 选 Clerk 的根本原因。

踩过的坑

  1. SaaS lock-in 是结构性的：用户表在 Clerk 云，password hash / passkey credential 都不导出。从 Clerk 迁到自托管基本意味着”全员重置密码”，比 better-auth 那种自己持有 schema 的方案沉没成本大得多。

  2. 价格在 50k+ MAU 后陡峭：10k 免费、10k-50k 每个 $0.02，1M MAU 一个月大约 $20k；同规模 better-auth 自托管只是一台 Postgres 的钱。

  3. Prebuilt UI 的”可定制”只是 className 注入：appearance.elements 只能改样式；想把 OAuth 按钮挪到表单上方、改字段顺序——必须用 useSignIn() headless 模式自己写整张表单，prebuilt UI 不接受布局级定制。

  4. 默认 telemetry 100% 上报：telemetry !== false 才关，文档不显眼。这是 SaaS 商业模式的弹药——它知道你用了哪些组件、哪个 OAuth provider，用来定价和销售。

适用 vs 不适用场景

适用：

  • B2B SaaS / 早期阶段 / hackathon / MVP / 个人 side project——10k MAU 内免费，省 1-2 个工程师月的体力活
  • 需要 Edge runtime middleware 的 Next.js 项目——Clerk 是 edge-native 一等公民
  • 需要”组织 + 邀请 + SAML + passkey + MFA”一站式的 B2B 应用
  • 团队不想把”用户管理”做成自己的产品功能

不适用：

  • MAU > 100k 且想长期省钱 → better-auth / auth-js 自托管
  • 数据合规要求”用户表必须在自己 DB”（GDPR / 中国大陆 / 金融监管）→ 自托管
  • 想完全控制 cookie 格式 / session schema → lucia（utility 派）
  • 已经在 supabase 全家桶里 → Supabase Auth（RLS 一致性最强）
  • 老牌 enterprise B2B 必须有 Auth0 logo → Auth0

历史小故事（可跳过）

  • 2013 年：Auth0 上线，把 OIDC 做成 SaaS。模式是”redirect 到 universal login → 回调”，让你登录的页面在 auth0.com 而不是你应用里。
  • 2020 年：React/Next.js 主导前端，开发者要的是 <SignIn /> 直接长在自己页面里，Auth0 那套 redirect 思维过时。
  • 2021 年：Colin Sidoti 和 Brayden Connor 在 YC W21 创办 Clerk Labs，launch HN 一句话定调：“These are not engineering problems, they are product features.”
  • 2022-2024 年：Linear、Cal.com、Vercel 自家产品都在用，B2B SaaS 圈的事实标准。
  • 2024 年：Edge runtime 的 cold start 优化、合并流（sign-in 自动转 sign-up）、passkey autofill 等推到 prebuilt UI。

学到什么

  1. “工程问题”和”产品功能”的边界可以重画——sign-in / org / invitation 在 2010 年是工程，在 2024 年是产品
  2. SDK 薄、SaaS 厚 的分层让”用户表归属”成为商业模式的核心分水岭，比 API 美感重要 100 倍
  3. Edge-native 不是 nice-to-have，是 2024 年起 auth library 的入场券
  4. Prebuilt UI 是真正的护城河——它把 fraud 防御、bot 拦截、passkey autofill 等长尾工程沉淀成 SaaS，对手抄不来

延伸阅读

  • 文档主页：clerk.com/docs（按框架分组，Next.js / React / Astro / Hono 都有 5 分钟 quickstart）
  • launch HN 讨论：news.ycombinator.com/item?id=27065848（2021-05，看创始人原话和当年质疑）
  • 源码 monorepo：github.com/clerk/javascript（22 包；packages/clerk-js/src/core/clerk.ts 是浏览器侧主体）
  • better-auth —— 想从 Clerk 迁到自托管，better-auth 是接近体验的 OSS 替代
  • auth-js —— Auth.js v5 也是 edge-native，但全套自己拼

关联

  • auth-js —— Next.js 圈的 OSS auth 标准，和 Clerk 的”自托管 vs SaaS”主路线对手
  • better-auth —— OSS plugin-first 的”接近 Clerk 体验自托管”路线
  • lucia —— utility-first 的极简派，和 Clerk 是两个极端
  • next-js —— Clerk 的最大宿主，clerkMiddleware 直接长在 App Router 上
  • react —— ClerkProvider / hooks / prebuilt UI 全部基于 React
  • hono —— Edge-first 框架，Clerk 提供 first-class 中间件
  • shadcn-ui —— 想从 Clerk prebuilt UI 切到自己拼组件时的常见去处

反向链接

  • appwrite —— Appwrite — 自己能装一遍的开源 Firebase
  • auth-js —— Auth.js — 让 OAuth 登录和会话存储变成两个抽象
  • better-auth —— better-auth — 把登录/OAuth/2FA/Passkey 拼成一行配置的 TS 认证框架
  • hono —— Hono — 多运行时 Web 框架
  • lucia —— Lucia — 主动把自己降级为”学习资源”的 TS 认证库
  • next-js —— Next.js — React 全栈框架
  • react —— React UI 组件库
  • shadcn-ui —— shadcn/ui — 把 React 组件从 npm 包变成”源码 + CLI 协议”
  • supabase —— Supabase — Firebase 的开源替代
  • supertokens —— SuperTokens — 自托管认证框架，把登录方式做成可拼装的 Recipe