Clerk Next.js 身份验证集成指南：快速实现用户登录与路由保护

clerk-nextjs-skills by gocallum/nextjs16-agent-skills

204 周安装量

18 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/gocallum/nextjs16-agent-skills --skill clerk-nextjs-skills

开发 JavaScript 框架安全

🇨🇳中文介绍

链接

快速开始

1. 安装依赖 (使用 pnpm)

pnpm add @clerk/nextjs
# 如需集成 MCP 服务器，同时安装：
pnpm add @vercel/mcp-adapter @clerk/mcp-tools

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

2. 创建 proxy.ts (Next.js 16)

proxy.ts 文件替代了 Next.js 15 中的 middleware.ts。在项目根目录或 /src 目录下创建：

// proxy.ts (或 src/proxy.ts)
import { clerkMiddleware } from '@clerk/nextjs/server'

export default clerkMiddleware()

export const config = {
  matcher: [
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    '/(api|trpc)(.*)',
  ],
}

3. 设置环境变量

在项目根目录创建 .env.local 文件：

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_publishable_key_here
CLERK_SECRET_KEY=your_secret_key_here
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/

4. 将 ClerkProvider 添加到布局

// app/layout.tsx
import {
  ClerkProvider,
  SignInButton,
  SignUpButton,
  SignedIn,
  SignedOut,
  UserButton,
} from '@clerk/nextjs'
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: '我的应用',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <ClerkProvider>
      <html lang="en">
        <body>
          <header className="flex justify-end items-center p-4 gap-4 h-16">
            <SignedOut>
              <SignInButton />
              <SignUpButton />
            </SignedOut>
            <SignedIn>
              <UserButton />
            </SignedIn>
          </header>
          {children}
        </body>
      </html>
    </ClerkProvider>
  )
}

5. 运行你的应用

访问 http://localhost:3000 并点击 "注册" 来创建你的第一个用户。

proxy.ts 与 middleware.ts

Next.js 16 (App Router) : 使用 proxy.ts 作为 Clerk 中间件
Next.js ≤15 : 使用 middleware.ts，代码完全相同（仅文件名不同）
Clerk 的 clerkMiddleware() 函数无论文件名如何都是相同的
matcher 配置确保了正确的路由处理和性能

默认情况下，clerkMiddleware() 不保护任何路由——所有路由都是公开的。使用 auth.protect() 来要求身份验证：

// 保护特定路由
import { auth } from '@clerk/nextjs/server'

export default async function Page() {
  const { userId } = await auth()
  
  if (!userId) {
    // 重定向由 clerkMiddleware 处理
  }
  
  return <div>为 {userId} 提供的受保护内容</div>
}

或者在 proxy.ts 中保护所有路由：

import { clerkMiddleware } from '@clerk/nextjs/server'

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

在运行时之前检查必需的 Clerk 密钥：

// lib/clerk-config.ts
export function validateClerkEnv() {
  const required = [
    'NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY',
    'CLERK_SECRET_KEY',
  ]
  
  const missing = required.filter(key => !process.env[key])
  
  if (missing.length > 0) {
    throw new Error(`缺少必需的 Clerk 环境变量: ${missing.join(', ')}`)
  }
}

在客户端组件中使用 Clerk 钩子：

// app/components/user-profile.tsx
'use client'

import { useUser } from '@clerk/nextjs'

export function UserProfile() {
  const { user, isLoaded } = useUser()
  
  if (!isLoaded) return <div>加载中...</div>
  
  if (!user) return <div>未登录</div>
  
  return (
    <div>
      <h1>{user.fullName}</h1>
      <p>{user.primaryEmailAddress?.emailAddress}</p>
    </div>
  )
}

或者在服务器组件/操作中使用：

// app/actions.ts
'use server'

import { auth, clerkClient } from '@clerk/nextjs/server'

export async function getUserData() {
  const { userId } = await auth()
  
  if (!userId) {
    throw new Error('未授权')
  }
  
  const clerk = await clerkClient()
  const user = await clerk.users.getUser(userId)
  
  return user
}

从 middleware.ts (Next.js 15) 迁移到 proxy.ts (Next.js 16)

重命名文件：将 middleware.ts 重命名为 proxy.ts（位置保持不变：根目录或 /src）

保持代码完全相同 - 无需功能更改：

// 迁移前 (middleware.ts)
import { clerkMiddleware } from '@clerk/nextjs/server'
export default clerkMiddleware()
export const config = { ... }

// 迁移后 (proxy.ts) - 代码相同
import { clerkMiddleware } from '@clerk/nextjs/server'
export default clerkMiddleware()
export const config = { ... }

更新 Next.js 版本：
```
pnpm add next@latest
```
验证环境变量 是否仍在 .env.local 中（无需更改）
测试迁移：
```
pnpm dev
```

如果路由未受保护，请确保 proxy.ts 位于正确的位置（根目录或 /src）
检查 .env.local 是否包含所有必需的 Clerk 密钥
如果中间件更改未生效，请清除 .next 缓存：rm -rf .next && pnpm dev
验证 Next.js 版本是否为 16.0+：pnpm list next

使用 Clerk 构建 MCP 服务器

完整的 MCP 服务器集成请参阅 CLERK_MCP_SERVER_SETUP.md。

MCP 快速设置摘要

安装 MCP 依赖：

pnpm add @vercel/mcp-adapter @clerk/mcp-tools

在 app/[transport]/route.ts 处创建 MCP 路由：

import { verifyClerkToken } from '@clerk/mcp-tools/next'
import { createMcpHandler, withMcpAuth } from '@vercel/mcp-adapter'
import { auth, clerkClient } from '@clerk/nextjs/server'

const clerk = await clerkClient()

const handler = createMcpHandler((server) => {
  server.tool(
    'get-clerk-user-data',
    '获取授权此请求的 Clerk 用户的数据',
    {},
    async (_, { authInfo }) => {
      const userId = authInfo!.extra!.userId! as string
      const userData = await clerk.users.getUser(userId)
      return {
        content: [{ type: 'text', text: JSON.stringify(userData) }],
      }
    },
  )
})

const authHandler = withMcpAuth(
  handler,
  async (_, token) => {
    const clerkAuth = await auth({ acceptsToken: 'oauth_token' })
    return verifyClerkToken(clerkAuth, token)
  },
  {
    required: true,
    resourceMetadataPath: '/.well-known/oauth-protected-resource/mcp',
  },
)

export { authHandler as GET, authHandler as POST }

公开 OAuth 元数据端点（完整设置请参阅参考资料）

更新 proxy.ts 以排除 .well-known 端点：

import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'

const isPublicRoute = createRouteMatcher([
  '/.well-known/oauth-authorization-server(.*)',
  '/.well-known/oauth-protected-resource(.*)',
])

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

在 Clerk 仪表板中启用动态客户端注册

1. 环境变量管理

开发时始终使用 .env.local（切勿提交敏感密钥）
在应用启动时验证环境变量
仅对可以安全暴露的非敏感密钥使用 NEXT_PUBLIC_ 前缀
对于生产环境，在你的部署平台（Vercel 等）中设置环境变量

2. 路由保护策略

// 选项 A: 保护所有路由
export default clerkMiddleware(async (auth, req) => {
  await auth.protect()
})

// 选项 B: 保护特定路由
import { createRouteMatcher } from '@clerk/nextjs/server'

const isProtectedRoute = createRouteMatcher(['/dashboard(.*)', '/api/user(.*)'])

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

// 选项 C: 公开路由，选择性地保护
const isPublicRoute = createRouteMatcher(['/sign-in(.*)', '/sign-up(.*)'])

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

3. MCP 服务器安全性

在 Clerk 仪表板中启用动态客户端注册
保持 .well-known 端点公开，但使用 OAuth 保护所有 MCP 工具
在 auth() 中使用 acceptsToken: 'oauth_token' 来要求机器令牌
OAuth 令牌在公开测试版期间免费（定价待定）
在暴露用户数据之前，始终使用 verifyClerkToken() 验证令牌

使用 clerkClient() 进行服务器端用户查询（自动缓存）
利用 React 服务器组件安全地访问用户数据
尽可能缓存用户数据以减少 API 调用
仅在客户端组件（'use client'）中使用 @clerk/nextjs 钩子

5. 生产环境部署

在你的部署平台中设置所有环境变量
使用 Clerk 的生产实例密钥（而非开发密钥）
在生产环境前，在预发布环境中测试身份验证流程
监控 Clerk 仪表板中的身份验证错误
保持 @clerk/nextjs 更新：pnpm update @clerk/nextjs

问题与解决方案

问题	解决方案
"缺少环境变量"	确保 `.env.local` 包含 `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` 和 `CLERK_SECRET_KEY`
中间件未保护路由	验证 `proxy.ts` 位于根目录或 `/src` 目录，而不是 `app/` 目录中
登录/注册页面不工作	检查 `.env.local` 中的 `NEXT_PUBLIC_CLERK_SIGN_IN_URL` 和 `NEXT_PUBLIC_CLERK_SIGN_UP_URL`
用户数据返回 null	确保用户已通过身份验证：调用 `getUser()` 前检查 `userId` 不为 null
MCP 服务器 OAuth 失败	在 Clerk 仪表板的 OAuth 应用程序中启用动态客户端注册
更改未生效	清除 `.next` 缓存：`rm -rf .next` 并重启 `pnpm dev`
"proxy.ts" 未被识别	验证 Next.js 版本为 16.0+：`pnpm list next`

常见的 Next.js 16 陷阱

文件命名：对于 Next.js 16，必须是 proxy.ts（而不是 middleware.ts）
位置：将 proxy.ts 放在项目根目录或 /src 目录中，不要放在 app/ 目录中
重新导出：必须从 proxy.ts 导出配置对象才能使匹配器生效
异步操作：clerkMiddleware() 支持异步；使用 await auth.protect() 进行路由保护

启用调试日志记录：

// proxy.ts
import { clerkMiddleware } from '@clerk/nextjs/server'

export default clerkMiddleware((auth, req) => {
  if (process.env.DEBUG_CLERK) {
    console.log('请求 URL:', req.nextUrl.pathname)
    console.log('用户 ID:', auth.sessionClaims?.sub)
  }
})

使用调试模式运行：

DEBUG_CLERK=1 pnpm dev

mcp-server-skills : 使用 Vercel 适配器的通用 MCP 服务器模式
nextjs16-skills : Next.js 16 功能、重大变更和最佳实践
authjs-skills : 使用 Auth.js（Auth0、GitHub 等）的替代身份验证方案

2026 年 1 月 21 日

🇺🇸English

Quick Start

1. Install Dependencies (Using pnpm)

pnpm add @clerk/nextjs
# For MCP server integration, also install:
pnpm add @vercel/mcp-adapter @clerk/mcp-tools

2. Create proxy.ts (Next.js 16)

The proxy.ts file replaces middleware.ts from Next.js 15. Create it at the root or in /src:

// proxy.ts (or src/proxy.ts)
import { clerkMiddleware } from '@clerk/nextjs/server'

export default clerkMiddleware()

export const config = {
  matcher: [
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    '/(api|trpc)(.*)',
  ],
}

3. Set Environment Variables

Create .env.local in your project root:

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_publishable_key_here
CLERK_SECRET_KEY=your_secret_key_here
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/

4. Add ClerkProvider to Layout

// app/layout.tsx
import {
  ClerkProvider,
  SignInButton,
  SignUpButton,
  SignedIn,
  SignedOut,
  UserButton,
} from '@clerk/nextjs'
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'My App',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <ClerkProvider>
      <html lang="en">
        <body>
          <header className="flex justify-end items-center p-4 gap-4 h-16">
            <SignedOut>
              <SignInButton />
              <SignUpButton />
            </SignedOut>
            <SignedIn>
              <UserButton />
            </SignedIn>
          </header>
          {children}
        </body>
      </html>
    </ClerkProvider>
  )
}

5. Run Your App

pnpm dev

Visit http://localhost:3000 and click "Sign Up" to create your first user.

Key Concepts

proxy.ts vs middleware.ts

Next.js 16 (App Router) : Use proxy.ts for Clerk middleware
Next.js ≤15 : Use middleware.ts with identical code (filename only differs)
Clerk's clerkMiddleware() function is the same regardless of filename
The matcher configuration ensures proper route handling and performance

Protecting Routes

By default, clerkMiddleware() does not protect routes—all are public. Use auth.protect() to require authentication:

// Protect specific route
import { auth } from '@clerk/nextjs/server'

export default async function Page() {
  const { userId } = await auth()
  
  if (!userId) {
    // Redirect handled by clerkMiddleware
  }
  
  return <div>Protected content for {userId}</div>
}

Or protect all routes in proxy.ts:

import { clerkMiddleware } from '@clerk/nextjs/server'

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

Environment Variable Validation

Check for required Clerk keys before runtime:

// lib/clerk-config.ts
export function validateClerkEnv() {
  const required = [
    'NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY',
    'CLERK_SECRET_KEY',
  ]
  
  const missing = required.filter(key => !process.env[key])
  
  if (missing.length > 0) {
    throw new Error(`Missing required Clerk environment variables: ${missing.join(', ')}`)
  }
}

Accessing User Data

Use Clerk hooks in client components:

// app/components/user-profile.tsx
'use client'

import { useUser } from '@clerk/nextjs'

export function UserProfile() {
  const { user, isLoaded } = useUser()
  
  if (!isLoaded) return <div>Loading...</div>
  
  if (!user) return <div>Not signed in</div>
  
  return (
    <div>
      <h1>{user.fullName}</h1>
      <p>{user.primaryEmailAddress?.emailAddress}</p>
    </div>
  )
}

Or in server components/actions:

// app/actions.ts
'use server'

import { auth, clerkClient } from '@clerk/nextjs/server'

export async function getUserData() {
  const { userId } = await auth()
  
  if (!userId) {
    throw new Error('Unauthorized')
  }
  
  const clerk = await clerkClient()
  const user = await clerk.users.getUser(userId)
  
  return user
}

Migrating from middleware.ts (Next.js 15) to proxy.ts (Next.js 16)

Step-by-Step Migration

Rename the file from middleware.ts to proxy.ts (location remains same: root or /src)

Keep the code identical - No functional changes needed:

// Before (middleware.ts)
import { clerkMiddleware } from '@clerk/nextjs/server'
export default clerkMiddleware()
export const config = { ... }

// After (proxy.ts) - Same code
import { clerkMiddleware } from '@clerk/nextjs/server'
export default clerkMiddleware()
export const config = { ... }

Update Next.js version :
```
pnpm add next@latest
```
Verify environment variables are still in .env.local (no changes needed)
:

Troubleshooting Migration

If routes aren't protected, ensure proxy.ts is in the correct location (root or /src)
Check that .env.local has all required Clerk keys
Clear .next cache if middleware changes don't take effect: rm -rf .next && pnpm dev
Verify Next.js version is 16.0+: pnpm list next

Building an MCP Server with Clerk

See CLERK_MCP_SERVER_SETUP.md for complete MCP server integration.

Quick MCP Setup Summary

Install MCP dependencies :

pnpm add @vercel/mcp-adapter @clerk/mcp-tools

Create MCP route at app/[transport]/route.ts:

import { verifyClerkToken } from '@clerk/mcp-tools/next'
import { createMcpHandler, withMcpAuth } from '@vercel/mcp-adapter'
import { auth, clerkClient } from '@clerk/nextjs/server'

const clerk = await clerkClient()

const handler = createMcpHandler((server) => {
  server.tool(
    'get-clerk-user-data',
    'Gets data about the Clerk user that authorized this request',
    {},
    async (_, { authInfo }) => {
      const userId = authInfo!.extra!.userId! as string
      const userData = await clerk.users.getUser(userId)
      return {
        content: [{ type: 'text', text: JSON.stringify(userData) }],
      }
    },
  )
})

const authHandler = withMcpAuth(
  handler,
  async (_, token) => {
    const clerkAuth = await auth({ acceptsToken: 'oauth_token' })
    return verifyClerkToken(clerkAuth, token)
  },
  {
    required: true,
    resourceMetadataPath: '/.well-known/oauth-protected-resource/mcp',
  },
)

export { authHandler as GET, authHandler as POST }

Best Practices

1. Environment Variable Management

Always use .env.local for development (never commit sensitive keys)
Validate environment variables on application startup
Use NEXT_PUBLIC_ prefix ONLY for non-sensitive keys that are safe to expose
For production, set environment variables in your deployment platform (Vercel, etc.)

2. Route Protection Strategies

// Option A: Protect all routes
export default clerkMiddleware(async (auth, req) => {
  await auth.protect()
})

// Option B: Protect specific routes
import { createRouteMatcher } from '@clerk/nextjs/server'

const isProtectedRoute = createRouteMatcher(['/dashboard(.*)', '/api/user(.*)'])

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

// Option C: Public routes with opt-in protection
const isPublicRoute = createRouteMatcher(['/sign-in(.*)', '/sign-up(.*)'])

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

3. MCP Server Security

Enable Dynamic Client Registration in Clerk Dashboard
Keep .well-known endpoints public but protect all MCP tools with OAuth
Use acceptsToken: 'oauth_token' in auth() to require machine tokens
OAuth tokens are free during public beta (pricing TBD)
Always verify tokens with verifyClerkToken() before exposing user data

4. Performance & Caching

Use clerkClient() for server-side user queries (cached automatically)
Leverage React Server Components for secure user data access
Cache user data when possible to reduce API calls
Use @clerk/nextjs hooks only in Client Components ('use client')

5. Production Deployment

Set all environment variables in your deployment platform
Use Clerk's production instance keys (not development keys)
Test authentication flow in staging environment before production
Monitor Clerk Dashboard for authentication errors
Keep @clerk/nextjs updated: pnpm update @clerk/nextjs

Troubleshooting

Issues & Solutions

Issue	Solution
"Missing environment variables"	Ensure `.env.local` has `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY`
Middleware not protecting routes	Verify `proxy.ts` is in root or `/src` directory, not in `app/`
Sign-in/sign-up pages not working	Check `NEXT_PUBLIC_CLERK_SIGN_IN_URL` and `NEXT_PUBLIC_CLERK_SIGN_UP_URL` in

Common Next.js 16 Gotchas

File naming : Must be proxy.ts (not middleware.ts) for Next.js 16
Location : Place proxy.ts at project root or in /src directory, NOT in app/
Re-exports : Config object must be exported from proxy.ts for matcher to work
Async operations : clerkMiddleware() is async-ready; use await auth.protect() for route protection

Debug Mode

Enable debug logging:

// proxy.ts
import { clerkMiddleware } from '@clerk/nextjs/server'

export default clerkMiddleware((auth, req) => {
  if (process.env.DEBUG_CLERK) {
    console.log('Request URL:', req.nextUrl.pathname)
    console.log('User ID:', auth.sessionClaims?.sub)
  }
})

Run with debug:

DEBUG_CLERK=1 pnpm dev

Related Skills

mcp-server-skills : General MCP server patterns with Vercel adapter
nextjs16-skills : Next.js 16 features, breaking changes, and best practices
authjs-skills : Alternative authentication using Auth.js (Auth0, GitHub, etc.)

Resources

Weekly Installs

204

Repository

gocallum/nextjs…t-skills

GitHub Stars

First Seen

Jan 21, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

gemini-cli148

opencode147

codex146

github-copilot137

claude-code133

cursor133

Azure RBAC 权限管理工具：查找最小角色、创建自定义角色与自动化分配

117,000 周安装

Test the migration

Expose OAuth metadata endpoints (see references for complete setup)

Update proxy.ts to exclude .well-known endpoints:

import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'

const isPublicRoute = createRouteMatcher([
  '/.well-known/oauth-authorization-server(.*)',
  '/.well-known/oauth-protected-resource(.*)',
])

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

Enable Dynamic Client Registration in Clerk Dashboard