auth

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Authentication Integrations

认证集成

You are an expert in authentication for Vercel-deployed applications — covering Clerk (native Vercel Marketplace integration), Descope, and Auth0.

您是Vercel部署应用的认证专家——涵盖Clerk（Vercel Marketplace原生集成）、Descope和Auth0。

Clerk (Recommended — Native Marketplace Integration)

Clerk（推荐——Marketplace原生集成）

Clerk is a native Vercel Marketplace integration with auto-provisioned environment variables and unified billing. Current SDK:

@clerk/nextjs

v7 (Core 3, March 2026).

Clerk是Vercel Marketplace的原生集成，支持自动配置环境变量和统一计费。当前SDK版本：

@clerk/nextjs

v7（Core 3，2026年3月）。

Install via Marketplace

通过Marketplace安装

bash

undefined

bash

undefined

Install Clerk from Vercel Marketplace (auto-provisions env vars)

从Vercel Marketplace安装Clerk（自动配置环境变量）

vercel integration add clerk


Auto-provisioned environment variables:
- `CLERK_SECRET_KEY` — server-side API key
- `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` — client-side publishable key

vercel integration add clerk


自动配置的环境变量：
- `CLERK_SECRET_KEY` —— 服务端API密钥
- `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` —— 客户端可发布密钥

SDK Setup

SDK设置

bash

undefined

bash

undefined

Install the Clerk Next.js SDK

安装Clerk Next.js SDK

npm install @clerk/nextjs

undefined

npm install @clerk/nextjs

undefined

Middleware Configuration

中间件配置

// middleware.ts
import { clerkMiddleware } from "@clerk/nextjs/server";

export default clerkMiddleware();

export const config = {
  matcher: [
    // Skip Next.js internals and static files
    "/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)",
    // Always run for API routes
    "/(api|trpc)(.*)",
  ],
};

// middleware.ts
import { clerkMiddleware } from "@clerk/nextjs/server";

export default clerkMiddleware();

export const config = {
  matcher: [
    // 跳过Next.js内部文件和静态文件
    "/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)",
    // 始终对API路由生效
    "/(api|trpc)(.*)",
  ],
};

Protect Routes

路由保护

// middleware.ts — protect specific routes
import { clerkMiddleware, createRouteMatcher } from "@clerk/nextjs/server";

const isProtectedRoute = createRouteMatcher(["/dashboard(.*)", "/api(.*)"]);

export default clerkMiddleware(async (auth, req) => {
  if (isProtectedRoute(req)) {
    await auth.protect();
  }
});

// middleware.ts —— 保护特定路由
import { clerkMiddleware, createRouteMatcher } from "@clerk/nextjs/server";

const isProtectedRoute = createRouteMatcher(["/dashboard(.*)", "/api(.*)"]);

export default clerkMiddleware(async (auth, req) => {
  if (isProtectedRoute(req)) {
    await auth.protect();
  }
});

Frontend API Proxy (Core 3)

前端API代理（Core 3）

Proxy Clerk's Frontend API through your own domain to avoid third-party requests:

// middleware.ts
export default clerkMiddleware({
  frontendApiProxy: { enabled: true },
});

通过自有域名代理Clerk的Frontend API，避免第三方请求：

// middleware.ts
export default clerkMiddleware({
  frontendApiProxy: { enabled: true },
});

Provider Setup

Provider配置

tsx

// app/layout.tsx
import { ClerkProvider } from "@clerk/nextjs";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <ClerkProvider>
      <html lang="en">
        <body>{children}</body>
      </html>
    </ClerkProvider>
  );
}

tsx

// app/layout.tsx
import { ClerkProvider } from "@clerk/nextjs";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <ClerkProvider>
      <html lang="en">
        <body>{children}</body>
      </html>
    </ClerkProvider>
  );
}

Sign-In and Sign-Up Pages

登录与注册页面

tsx

// app/sign-in/[[...sign-in]]/page.tsx
import { SignIn } from "@clerk/nextjs";

export default function Page() {
  return <SignIn />;
}

tsx

// app/sign-up/[[...sign-up]]/page.tsx
import { SignUp } from "@clerk/nextjs";

export default function Page() {
  return <SignUp />;
}

Add routing env vars to

.env.local

env

NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up

tsx

// app/sign-in/[[...sign-in]]/page.tsx
import { SignIn } from "@clerk/nextjs";

export default function Page() {
  return <SignIn />;
}

tsx

// app/sign-up/[[...sign-up]]/page.tsx
import { SignUp } from "@clerk/nextjs";

export default function Page() {
  return <SignUp />;
}

在

.env.local

中添加路由环境变量：

env

NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up

Access User Data

获取用户数据

tsx

// Server component
import { currentUser } from "@clerk/nextjs/server";

export default async function Page() {
  const user = await currentUser();
  return <p>Hello, {user?.firstName}</p>;
}

tsx

// Client component
"use client";
import { useUser } from "@clerk/nextjs";

export default function UserGreeting() {
  const { user, isLoaded } = useUser();
  if (!isLoaded) return null;
  return <p>Hello, {user?.firstName}</p>;
}

tsx

// 服务端组件
import { currentUser } from "@clerk/nextjs/server";

export default async function Page() {
  const user = await currentUser();
  return <p>你好，{user?.firstName}</p>;
}

tsx

// 客户端组件
"use client";
import { useUser } from "@clerk/nextjs";

export default function UserGreeting() {
  const { user, isLoaded } = useUser();
  if (!isLoaded) return null;
  return <p>你好，{user?.firstName}</p>;
}

API Route Protection

API路由保护

// app/api/protected/route.ts
import { auth } from "@clerk/nextjs/server";

export async function GET() {
  const { userId } = await auth();
  if (!userId) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }
  return Response.json({ userId });
}

// app/api/protected/route.ts
import { auth } from "@clerk/nextjs/server";

export async function GET() {
  const { userId } = await auth();
  if (!userId) {
    return Response.json({ error: "未授权" }, { status: 401 });
  }
  return Response.json({ userId });
}

Descope

Descope is available on the Vercel Marketplace with native integration support.

Descope已在Vercel Marketplace上线，支持原生集成。

Install via Marketplace

通过Marketplace安装

bash

vercel integration add descope

bash

vercel integration add descope

SDK Setup

SDK设置

bash

npm install @descope/nextjs-sdk

bash

npm install @descope/nextjs-sdk

Provider and Middleware

Provider与中间件

tsx

// app/layout.tsx
import { AuthProvider } from "@descope/nextjs-sdk";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <AuthProvider projectId={process.env.NEXT_PUBLIC_DESCOPE_PROJECT_ID!}>
      <html lang="en">
        <body>{children}</body>
      </html>
    </AuthProvider>
  );
}

// middleware.ts
import { authMiddleware } from "@descope/nextjs-sdk/server";

export default authMiddleware({
  projectId: process.env.DESCOPE_PROJECT_ID!,
  publicRoutes: ["/", "/sign-in"],
});

tsx

// app/layout.tsx
import { AuthProvider } from "@descope/nextjs-sdk";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <AuthProvider projectId={process.env.NEXT_PUBLIC_DESCOPE_PROJECT_ID!}>
      <html lang="en">
        <body>{children}</body>
      </html>
    </AuthProvider>
  );
}

// middleware.ts
import { authMiddleware } from "@descope/nextjs-sdk/server";

export default authMiddleware({
  projectId: process.env.DESCOPE_PROJECT_ID!,
  publicRoutes: ["/", "/sign-in"],
});

Sign-In Flow

登录流程

tsx

"use client";
import { Descope } from "@descope/nextjs-sdk";

export default function SignInPage() {
  return <Descope flowId="sign-up-or-in" />;
}

tsx

"use client";
import { Descope } from "@descope/nextjs-sdk";

export default function SignInPage() {
  return <Descope flowId="sign-up-or-in" />;
}

Auth0

Auth0 provides a mature authentication platform with extensive identity provider support.

Auth0提供成熟的认证平台，支持多种身份提供商。

SDK Setup

SDK设置

bash

npm install @auth0/nextjs-auth0

bash

npm install @auth0/nextjs-auth0

Configuration

配置

// lib/auth0.ts
import { Auth0Client } from "@auth0/nextjs-auth0/server";

export const auth0 = new Auth0Client();

Required environment variables:

env

AUTH0_SECRET=<random-secret>
AUTH0_BASE_URL=http://localhost:3000
AUTH0_ISSUER_BASE_URL=https://your-tenant.auth0.com
AUTH0_CLIENT_ID=<client-id>
AUTH0_CLIENT_SECRET=<client-secret>

// lib/auth0.ts
import { Auth0Client } from "@auth0/nextjs-auth0/server";

export const auth0 = new Auth0Client();

所需环境变量：

env

AUTH0_SECRET=<随机密钥>
AUTH0_BASE_URL=http://localhost:3000
AUTH0_ISSUER_BASE_URL=https://your-tenant.auth0.com
AUTH0_CLIENT_ID=<客户端ID>
AUTH0_CLIENT_SECRET=<客户端密钥>

Middleware

中间件

// middleware.ts
import { auth0 } from "@/lib/auth0";
import { NextRequest, NextResponse } from "next/server";

export async function middleware(request: NextRequest) {
  return await auth0.middleware(request);
}

export const config = {
  matcher: [
    "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
  ],
};

// middleware.ts
import { auth0 } from "@/lib/auth0";
import { NextRequest, NextResponse } from "next/server";

export async function middleware(request: NextRequest) {
  return await auth0.middleware(request);
}

export const config = {
  matcher: [
    "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
  ],
};

Access Session Data

获取会话数据

tsx

// Server component
import { auth0 } from "@/lib/auth0";

export default async function Page() {
  const session = await auth0.getSession();
  return session ? (
    <p>Hello, {session.user.name}</p>
  ) : (
    <a href="/auth/login">Log in</a>
  );
}

tsx

// 服务端组件
import { auth0 } from "@/lib/auth0";

export default async function Page() {
  const session = await auth0.getSession();
  return session ? (
    <p>你好，{session.user.name}</p>
  ) : (
    <a href="/auth/login">登录</a>
  );
}

Decision Matrix

决策矩阵

Need	Recommended	Why
Fastest setup on Vercel	Clerk	Native Marketplace, auto-provisioned env vars
Passwordless / social login flows	Descope	Visual flow builder, Marketplace native
Enterprise SSO / SAML / multi-tenant	Auth0	Deep enterprise identity support
Pre-built UI components	Clerk	Drop-in `<SignIn />` , `<UserButton />`
Vercel unified billing	Clerk or Descope	Both are native Marketplace integrations

需求	推荐方案	原因
Vercel上最快的搭建流程	Clerk	Marketplace原生集成，自动配置环境变量
无密码/社交登录流程	Descope	可视化流程构建器，Marketplace原生支持
企业级SSO/SAML/多租户	Auth0	完善的企业身份管理支持
预构建UI组件	Clerk	开箱即用的 `<SignIn />` 、 `<UserButton />` 组件
Vercel统一计费	Clerk或Descope	均为Marketplace原生集成

Clerk Core 3 Breaking Changes (March 2026)

Clerk Core 3 破坏性变更（2026年3月）

Clerk provides an upgrade CLI that scans your codebase and applies codemods:

npx @clerk/upgrade

. Requires Node.js 20.9.0+.

auth()
is async — always use
```
const { userId } = await auth()
```
, not synchronous
auth.protect()
moved — use
```
await auth.protect()
```
directly, not from the return value of
```
auth()
```
clerkClient()
is async — use
```
await clerkClient()
```
in middleware handlers
authMiddleware()
removed — migrate to
```
clerkMiddleware()
```
@clerk/types
deprecated — import types from SDK subpath exports:
```
import type { UserResource } from '@clerk/react/types'
```
(works from any SDK package)
ClerkProvider
no longer forces dynamic rendering — pass the
```
dynamic
```
prop if needed
Cache components — when using Next.js cache components, place
```
<ClerkProvider>
```
inside
```
<body>
```
, not wrapping
```
<html>
```
Satellite domains — new
```
satelliteAutoSync
```
option skips handshake redirects when no session cookies exist
Smaller bundles — React is now shared across framework SDKs (~50KB gzipped savings)
Better offline handling —
```
getToken()
```
now correctly distinguishes signed-out from offline states

Clerk提供升级CLI，可扫描代码库并自动应用修改：

npx @clerk/upgrade

。要求Node.js 20.9.0+。

auth()
为异步方法 —— 始终使用
```
const { userId } = await auth()
```
，而非同步调用
auth.protect()
迁移 —— 直接使用
```
await auth.protect()
```
，而非从
```
auth()
```
的返回值中调用
clerkClient()
为异步方法 —— 在中间件处理程序中使用
```
await clerkClient()
```
authMiddleware()
已移除 —— 迁移至
```
clerkMiddleware()
```
@clerk/types
已废弃 —— 从SDK子路径导出中导入类型：
```
import type { UserResource } from '@clerk/react/types'
```
（适用于所有SDK包）
ClerkProvider
不再强制动态渲染 —— 如需动态渲染，传递
```
dynamic
```
属性
缓存组件 —— 使用Next.js缓存组件时，将
```
<ClerkProvider>
```
放置在
```
<body>
```
内部，而非包裹
```
<html>
```
卫星域名 —— 新增
```
satelliteAutoSync
```
选项，当无会话Cookie时跳过握手重定向
更小的包体积 —— React现在在框架SDK间共享（约节省50KB gzip压缩后体积）
更好的离线处理 ——
```
getToken()
```
现在可正确区分已登出和离线状态

Cross-References

交叉引用

Marketplace install and env var provisioning →
```
⤳ skill: marketplace
```
Middleware routing patterns →
```
⤳ skill: routing-middleware
```
Environment variable management →
```
⤳ skill: env-vars
```
Vercel OAuth (Sign in with Vercel) →
```
⤳ skill: sign-in-with-vercel
```

Marketplace安装与环境变量配置 →
```
⤳ skill: marketplace
```
中间件路由模式 →
```
⤳ skill: routing-middleware
```
环境变量管理 →
```
⤳ skill: env-vars
```
Vercel OAuth（使用Vercel登录） →
```
⤳ skill: sign-in-with-vercel
```

auth

Original

Translation

Authentication Integrations

认证集成

Clerk (Recommended — Native Marketplace Integration)

Clerk（推荐——Marketplace原生集成）

Install via Marketplace

通过Marketplace安装

Install Clerk from Vercel Marketplace (auto-provisions env vars)

从Vercel Marketplace安装Clerk（自动配置环境变量）

SDK Setup

SDK设置

Install the Clerk Next.js SDK

安装Clerk Next.js SDK

Middleware Configuration

中间件配置

Protect Routes

路由保护

Frontend API Proxy (Core 3)

前端API代理（Core 3）

Provider Setup

Provider配置

Sign-In and Sign-Up Pages

登录与注册页面

Access User Data

获取用户数据

API Route Protection

API路由保护

Descope

Descope

Install via Marketplace

通过Marketplace安装

SDK Setup

SDK设置

Provider and Middleware

Provider与中间件

Sign-In Flow

登录流程

Auth0

Auth0

SDK Setup

SDK设置

Configuration

配置

Middleware

中间件

Access Session Data

获取会话数据

Decision Matrix

决策矩阵

Clerk Core 3 Breaking Changes (March 2026)

Clerk Core 3 破坏性变更（2026年3月）

Cross-References

交叉引用

Official Documentation

官方文档