Clerk 用户认证完全指南：现代 Web 应用开发实战

Clerk 用户认证完全指南：现代 Web 应用开发实战 | 极客日志

import { SignIn } from '@clerk/nextjs'
export default function Page() {
  return <SignIn />
}

# 对于 Next.js 项目
npm install @clerk/nextjs
# 对于纯 React 项目
npm install @clerk/clerk-react

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxxxx
CLERK_SECRET_KEY=sk_test_xxxxx

// app/layout.tsx (Next.js App Router)
import { ClerkProvider } from '@clerk/nextjs'

export default function RootLayout({ children }) {
  return (
    <ClerkProvider>
      <html lang="zh">
        <body>{children}</body>
      </html>
    </ClerkProvider>
  )
}

// app/page.tsx
import { SignInButton, SignUpButton, UserButton, useUser } from '@clerk/nextjs'

export default function Home() {
  const { isSignedIn, user } = useUser()
  return (
    <div>
      <header>
        {isSignedIn ? (
          <div>
            <span>欢迎，{user.firstName}!</span>
            <UserButton />
          </div>
        ) : (
          <div>
            <SignInButton mode="modal">
              <button>登录</button>
            </SignInButton>
            <SignUpButton mode="modal">
              <button>注册</button>
            </SignUpButton>
          </div>
        )}
      </header>
      <main>
        {isSignedIn ? (
          <h1>你已登录，这是受保护的内容</h1>
        ) : (
          <h1>请登录以查看内容</h1>
        )}
      </main>
    </div>
  )
}

// app/dashboard/page.tsx
import { auth } from '@clerk/nextjs'
import { redirect } from 'next/navigation'

export default function Dashboard() {
  const { userId } = auth()
  if (!userId) {
    redirect('/sign-in')
  }
  return <div>受保护的仪表板内容</div>
}

// middleware.ts
import { authMiddleware } from '@clerk/nextjs'

export default authMiddleware({
  // 公开路由，不需要登录
  publicRoutes: ['/', '/about', '/blog(.*)'],
  // 忽略的路由（API 路由等）
  ignoredRoutes: ['/api/webhook'],
})

export const config = {
  matcher: ['/((?!.+\.[\w]+$|_next).*)', '/', '/(api|trpc)(.*)'],
}

'use client'
import { useUser } from '@clerk/nextjs'

export default function Profile() {
  const { user, isLoaded } = useUser()
  if (!isLoaded) return <div>加载中...</div>
  if (!user) return <div>未登录</div>
  return (
    <div>
      <img src={user.imageUrl} alt="头像" />
      <h2>{user.fullName}</h2>
      <p>邮箱：{user.primaryEmailAddress?.emailAddress}</p>
      <p>用户 ID: {user.id}</p>
    </div>
  )
}

import { currentUser } from '@clerk/nextjs'

export default async function ServerProfile() {
  const user = await currentUser()
  return <div>欢迎，{user?.firstName}</div>
}

const { user } = useUser()
// 访问自定义字段
const companyName = user?.publicMetadata?.companyName
const jobTitle = user?.publicMetadata?.jobTitle

'use client'
import { 
  useOrganization, 
  useOrganizationList, 
  OrganizationSwitcher 
} from '@clerk/nextjs'

export default function TeamDashboard() {
  const { organization } = useOrganization()
  const { organizationList } = useOrganizationList()
  return (
    <div>
      {/* 组织切换器 */}
      <OrganizationSwitcher />
      <h2>当前组织：{organization?.name}</h2>
      {/* 显示用户加入的所有组织 */}
      <ul>
        {organizationList?.map(org => (
          <li key={org.id}>{org.name}</li>
        ))}
      </ul>
    </div>
  )
}

// app/api/webhooks/clerk/route.ts
import { Webhook } from 'svix'
import { headers } from 'next/headers'

export async function POST(req: Request) {
  const WEBHOOK_SECRET = process.env.CLERK_WEBHOOK_SECRET
  const headerPayload = headers()
  const svix_id = headerPayload.get('svix-id')
  const svix_timestamp = headerPayload.get('svix-timestamp')
  const svix_signature = headerPayload.get('svix-signature')
  const payload = await req.json()
  const body = JSON.stringify(payload)
  const wh = new Webhook(WEBHOOK_SECRET)
  let evt

  try {
    evt = wh.verify(body, {
      'svix-id': svix_id,
      'svix-timestamp': svix_timestamp,
      'svix-signature': svix_signature,
    })
  } catch (err) {
    return new Response('验证失败', { status: 400 })
  }

  // 处理不同的事件类型
  const eventType = evt.type
  if (eventType === 'user.created') {
    const { id, email_addresses, first_name, last_name } = evt.data
    // 在你的数据库中创建用户记录
    await db.users.create({
      clerkId: id,
      email: email_addresses[0].email_address,
      firstName: first_name,
      lastName: last_name,
    })
  }
  return new Response('OK', { status: 200 })
}

// app/api/protected/route.ts
import { auth } from '@clerk/nextjs'

export async function GET() {
  const { userId } = auth()
  if (!userId) {
    return new Response('未授权', { status: 401 })
  }
  // 处理已授权的请求
  const data = await fetchUserData(userId)
  return Response.json(data)
}

// Node.js/Express 示例
const { createClerkClient } = require('@clerk/backend')
const clerkClient = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })

app.get('/api/protected', async (req, res) => {
  const token = req.headers.authorization?.replace('Bearer ', '')
  try {
    const verified = await clerkClient.verifyToken(token)
    const userId = verified.sub // 处理请求
    res.json({ message: 'Success', userId })
  } catch (error) {
    res.status(401).json({ error: 'Unauthorized' })
  }
})

<ClerkProvider appearance={{ 
  variables: { 
    colorPrimary: '#FF6B6B', 
    colorBackground: '#1a1a1a', 
    colorText: '#ffffff', 
    borderRadius: '8px', 
    fontFamily: '"Inter", sans-serif', 
  }, 
  elements: { 
    formButtonPrimary: { 
      fontSize: '16px', 
      textTransform: 'none', 
      backgroundColor: '#FF6B6B', 
      '&:hover': { 
        backgroundColor: '#FF5252', 
      }, 
    }, 
    card: { 
      boxShadow: '0 4px 6px rgba(0, 0, 0, 0.1)', 
    }, 
  }, 
}} >
  {children}
</ClerkProvider>

<ClerkProvider localization={zhCN}>
  {children}
</ClerkProvider>

特性	Clerk	Auth0
易用性	⭐⭐⭐⭐⭐ 开箱即用	⭐⭐⭐ 配置复杂
UI 组件	内置精美 UI	需自行构建
现代框架支持	优秀（React/Next.js）	一般
免费额度	10,000 MAU	7,000 MAU
定价	$25/月起	$35/月起
文档质量	优秀	详尽但复杂
企业功能	支持 SAML SSO	更全面
目标用户	现代 Web 应用开发者	大型企业

特性	Clerk	Firebase Auth
独立性	完全独立	依赖 Firebase 生态
UI 组件	内置完整 UI	FirebaseUI 较基础
用户管理	强大的 Dashboard	基础功能
定价	按 MAU	免费（但需要 Firebase）
现代框架	优秀	一般
组织管理	原生支持	需自行实现

特性	Clerk	Supabase Auth
UI 组件	精美开箱即用	需自行构建
免费额度	10,000 MAU	50,000 MAU
完整性	专注认证	数据库 + 认证 + 存储
开发体验	极佳	优秀
开源	否	是
自托管	否	支持

特性	Clerk	NextAuth.js
托管方式	SaaS（托管）	自托管
UI 组件	完整 UI	基础 UI
配置复杂度	极简	中等
定价	付费（有免费版）	完全免费
灵活性	高但有限制	完全控制
维护成本	零	需自行维护

// 用户可以创建多个工作空间
<OrganizationSwitcher />
// 只有管理员可以访问设置
const { membership } = useOrganization()
if (membership?.role === 'admin') {
  // 显示管理功能
}

// 评论功能
const { user } = useUser()
function Comment() {
  return (
    <div>
      <img src={user.imageUrl} />
      <p>{user.fullName}</p>
      <textarea placeholder="发表评论..." />
    </div>
  )
}

// 结账时确保用户已登录
const { userId } = auth()
if (!userId) {
  redirect('/sign-in?redirect_url=/checkout')
}
// 使用 Clerk 用户 ID 创建 Stripe 客户
const stripeCustomer = await stripe.customers.create({
  email: user.primaryEmailAddress,
  metadata: { clerkUserId: userId }
})

// 检查用户剩余额度
const { user } = useUser()
const creditsLeft = user?.publicMetadata?.credits || 0
if (creditsLeft <= 0) {
  return <UpgradePrompt />
}

// 错误做法 ❌
export default function AdminPage() {
  const { user } = useUser() // 仅在客户端检查，不安全
  if (!user) return <div>请登录</div>
  return <AdminDashboard />
}

// 正确做法 ✅
export default async function AdminPage() {
  const { userId } = auth() // 服务端验证
  if (!userId) redirect('/sign-in')
  return <AdminDashboard />
}

// middleware.ts
import { authMiddleware } from '@clerk/nextjs'
export default authMiddleware({
  publicRoutes: ['/', '/about', '/blog(.*)'],
})
// 这比在每个页面单独验证更高效

// app/layout.tsx
import { currentUser } from '@clerk/nextjs'

export default async function Layout() {
  const user = await currentUser() // 预先获取用户数据，避免瀑布式请求
  return <YourApp initialUser={user} />
}

import dynamic from 'next/dynamic'
const UserProfile = dynamic(() => import('@clerk/nextjs').then(mod => mod.UserProfile), { ssr: false })

<SignIn afterSignInUrl="/dashboard" afterSignUpUrl="/onboarding" redirectUrl="/welcome" />

<ClerkProvider appearance={{ layout: { socialButtonsPlacement: 'top', socialButtonsVariant: 'iconButton', } }} >

// app/api/webhooks/clerk/route.ts
import { db } from '@/lib/db'

export async function POST(req: Request) {
  const evt = await verifyWebhook(req)
  if (evt.type === 'user.created') {
    await db.users.create({
      clerkId: evt.data.id,
      email: evt.data.email_addresses[0].email_address,
      createdAt: new Date(evt.data.created_at),
    })
  }
  if (evt.type === 'user.updated') {
    await db.users.update({
      where: { clerkId: evt.data.id },
      data: {
        email: evt.data.email_addresses[0].email_address,
        firstName: evt.data.first_name,
        lastName: evt.data.last_name,
      }
    })
  }
  if (evt.type === 'user.deleted') {
    await db.users.delete({ where: { clerkId: evt.data.id } })
  }
  return new Response('OK', { status: 200 })
}

Clerk 用户认证完全指南：现代 Web 应用开发实战

前言

一、Clerk 的诞生：解决开发者痛点的故事

1.1 创始团队与创立背景

1.2 市场现状与痛点

1.3 Clerk 的诞生理念

二、Clerk 到底是什么？

2.1 核心定位

2.2 核心功能模块

2.2.1 用户认证（Authentication）

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具

2.2.2 用户管理（User Management）

2.2.3 组织管理（Organizations）

2.2.4 自定义化

三、为什么 Clerk 能够成功？

3.1 技术优势

3.1.1 极致的开发者体验

3.1.2 原生支持现代框架

3.1.3 边缘计算优化

3.2 产品设计优势

3.2.1 美观的默认 UI

3.2.2 一致的用户体验

3.3 商业模式优势

3.3.1 慷慨的免费计划

3.3.2 合理的定价

四、Clerk 的实际使用指南

4.1 快速开始（5 分钟集成）

4.2 进阶功能

4.2.1 保护路由

4.2.2 获取用户信息

4.2.3 自定义用户字段

4.2.4 组织功能（多租户）

4.2.5 Webhooks 集成

4.3 与后端 API 集成

4.3.1 验证 JWT Token

4.3.2 在外部后端使用

4.4 UI 定制化

4.4.1 主题定制

4.4.2 本地化（中文支持）

五、Clerk 与其他方案对比

5.1 Clerk vs Auth0

5.2 Clerk vs Firebase Authentication

5.3 Clerk vs Supabase Auth

5.4 Clerk vs NextAuth.js

六、实际应用案例

6.1 SaaS 应用

6.2 内容平台

6.3 电商平台

6.4 AI 应用

七、Clerk 的生态系统与社区

7.1 官方资源

7.2 第三方集成

7.3 学习资源

八、常见问题与最佳实践

8.1 常见问题

8.2 最佳实践

8.2.1 安全实践

8.2.2 性能优化

8.2.3 用户体验优化

8.2.4 数据同步策略

九、Clerk 的未来发展方向

9.1 AI 时代的身份认证

9.2 产品扩展

9.3 生态系统建设

十、适合你吗？Clerk 的选择指南

10.1 完美适合的场景

10.2 可能不太适合的场景

10.3 决策建议

十一、总结与展望

参考资料

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具