Back to Details

clerk

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Clerk

Clerk

Clerk is a comprehensive user management and authentication service built specifically for the modern web (React, Next.js, Remix). It focuses on providing "Drop-in" UI components (
<SignIn />
, 
<UserProfile />
) rather than just APIs.
Clerk是一款专为现代Web应用（React、Next.js、Remix）打造的综合性用户管理与身份验证服务。它专注于提供“即插即用”的UI组件（
<SignIn />
、
<UserProfile />
），而非仅提供API。

When to Use

适用场景

  • Next.js / React Apps: Best-in-class integration with App Router and Server Components.
  • SaaS B2B/B2C: Built-in Organization (Multi-tenancy) management.
  • Speed: You want the User Profile, Avatar upload, and Email management UI done for you.
  • Next.js / React应用：与App Router和Server Components的集成表现业界领先。
  • SaaS B2B/B2C：内置组织（多租户）管理功能。
  • 追求开发效率：你希望直接使用现成的用户资料、头像上传和邮件管理UI。

Quick Start (Next.js App Router)

快速开始（Next.js App Router）

typescript
// middleware.ts
import { authMiddleware } from "@clerk/nextjs";
export default authMiddleware({});

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

// page.tsx (Protected)
import { UserButton, currentUser } from "@clerk/nextjs";
export default async function Page() {
  const user = await currentUser();
  if (!user) return <div>Not signed in</div>;
  return <header>Welcome {user.firstName} <UserButton /></header>;
}
typescript
// middleware.ts
import { authMiddleware } from "@clerk/nextjs";
export default authMiddleware({});

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

// page.tsx (Protected)
import { UserButton, currentUser } from "@clerk/nextjs";
export default async function Page() {
  const user = await currentUser();
  if (!user) return <div>Not signed in</div>;
  return <header>Welcome {user.firstName} <UserButton /></header>;
}

Core Concepts

核心概念

Pre-built Components

预构建组件

Clerk provides the full UI: Login, Register, Forgot Password, Managed MFA, User Profile (Change Password, 2FA, Sessions).
Clerk提供完整的UI：登录、注册、找回密码、托管式MFA、用户资料（修改密码、双因素认证、会话管理）。

Sessions vs Tokens

会话与令牌

Clerk handles the complexity of short-lived JWTs (
__session
cookie) and keeps them fresh automatically via frontend SDKs.
Clerk会处理短期JWT（
__session
cookie）的复杂性，并通过前端SDK自动保持令牌更新。

Best Practices (2025)

2025年最佳实践

Do:
  • Use Server Components (
    currentUser()
    ) to fetch user data on the backend.
  • Use Organizations feature for B2B SaaS apps (Tenant isolation).
  • Enable Passkeys (Passwordless) in the dashboard (Clerk supports this natively).
Don't:
  • Don't try to build custom UI unless necessary. The pre-built components handle edge cases (MFA, Captcha, Error states) perfectly.
  • Don't expose Secret Keys in client-side env vars.
建议：
  • 使用Server Components（
    currentUser()
    ）在后端获取用户数据。
  • 针对B2B SaaS应用使用Organizations功能（租户隔离）。
  • 在控制台中启用Passkeys（无密码登录）功能（Clerk原生支持）。
避免：
  • 除非必要，不要尝试构建自定义UI。预构建组件已完美处理边缘情况（MFA、验证码、错误状态）。
  • 不要在客户端环境变量中暴露密钥。

Troubleshooting

故障排查

ErrorCauseSolution
401 Unauthorized
Middleware not configured.Ensure 
middleware.ts
matches all routes (
/((?!...))
).
Hydration Error
HTML mismatch.Wrap app in 
<ClerkProvider>
.
错误原因解决方案
401 Unauthorized
未配置中间件确保
middleware.ts
匹配所有路由（
/((?!...))
）。
Hydration Error
HTML内容不匹配将应用包裹在
<ClerkProvider>
中。

References

参考资料