clerk-nuxt-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Nuxt Patterns

Nuxt 认证模式

What Do You Need?

你需要实现什么功能？

Task	Reference
Protect routes with middleware	references/nuxt-middleware.md
Auth in server API routes (Nitro)	references/server-api-routes.md
useAuth / useUser in components	references/composables.md
SSR-safe auth patterns	references/ssr-auth.md

任务	参考文档
通过中间件保护路由	references/nuxt-middleware.md
服务端API路由（Nitro）身份认证	references/server-api-routes.md
在组件中使用useAuth / useUser	references/composables.md
SSR安全的身份认证模式	references/ssr-auth.md

References

参考列表

Reference	Description
`references/nuxt-middleware.md`	Route protection, clerkMiddleware()
`references/server-api-routes.md`	Nitro server route auth
`references/composables.md`	useAuth, useUser, useClerk
`references/ssr-auth.md`	SSR hydration, server vs client

参考文档	说明
`references/nuxt-middleware.md`	路由保护、clerkMiddleware()
`references/server-api-routes.md`	Nitro服务端路由认证
`references/composables.md`	useAuth、useUser、useClerk
`references/ssr-auth.md`	SSR水合、服务端 vs 客户端差异

Setup

安装配置

npm install @clerk/nuxt

.env

NUXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
NUXT_CLERK_SECRET_KEY=sk_...

nuxt.config.ts

typescript

export default defineNuxtConfig({
  modules: ['@clerk/nuxt'],
})

This single line auto-configures middleware, plugins, and component auto-imports.

npm install @clerk/nuxt

.env

配置：

NUXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
NUXT_CLERK_SECRET_KEY=sk_...

nuxt.config.ts

配置：

typescript

export default defineNuxtConfig({
  modules: ['@clerk/nuxt'],
})

这一行代码会自动配置中间件、插件以及组件自动导入能力。

Mental Model

核心逻辑模型

@clerk/nuxt

auto-imports all Clerk components and composables — no explicit imports needed in

<script setup>

Composables (
```
useAuth
```
,
```
useUser
```
) — client-side reactive, inside
```
<script setup>
```
Server routes (
```
clerkClient
```
) — Nitro server routes,
```
event.context.auth
```
Middleware (
```
clerkMiddleware
```
) — auto-registered, use
```
auth().protect()
```
to lock routes

@clerk/nuxt

会自动导入所有Clerk组件和composables，无需在

<script setup>

中显式导入。

Composables（
```
useAuth
```
、
```
useUser
```
）—— 客户端响应式能力，在
```
<script setup>
```
中使用
服务端路由（
```
clerkClient
```
）—— 适用于Nitro服务端路由，通过
```
event.context.auth
```
获取认证信息
中间件（
```
clerkMiddleware
```
）—— 自动注册，可使用
```
auth().protect()
```
锁定路由访问权限

Minimal Pattern

最简实现模式

vue

<!-- pages/dashboard.vue -->
<script setup lang="ts">
definePageMeta({ middleware: 'auth' })
const { userId } = useAuth()
</script>

<template>
  <Show when="signed-in">
    <p>Hello {{ userId }}</p>
  </Show>
</template>

definePageMeta({ middleware: 'auth' })
uses the built-in auth middleware from
@clerk/nuxt
.

vue

<!-- pages/dashboard.vue -->
<script setup lang="ts">
definePageMeta({ middleware: 'auth' })
const { userId } = useAuth()
</script>

<template>
  <Show when="signed-in">
    <p>你好 {{ userId }}</p>
  </Show>
</template>

definePageMeta({ middleware: 'auth' })
使用的是
@clerk/nuxt
内置的身份认证中间件。

Common Pitfalls

常见问题排查

Symptom	Cause	Fix
Composables return `undefined` on server	useAuth is client-only	Use `event.context.auth` in server routes
Route not protected	Missing `middleware: 'auth'` meta	Add `definePageMeta({ middleware: 'auth' })`
`clerkClient` not available	Wrong import path	Import from `@clerk/nuxt/server`
Hydration mismatch	Rendering auth state before mounted	Wrap in `<ClientOnly>` or check `isLoaded`
Env vars not picked up	Wrong prefix	Nuxt requires `NUXT_PUBLIC_` for public, `NUXT_` for server

现象	原因	解决方案
Composables在服务端返回 `undefined`	useAuth仅支持客户端	在服务端路由中使用 `event.context.auth`
路由未被保护	缺少 `middleware: 'auth'` 元数据	添加 `definePageMeta({ middleware: 'auth' })`
`clerkClient` 不可用	导入路径错误	从 `@clerk/nuxt/server` 导入
水合不匹配	组件挂载前就渲染了认证状态	用 `<ClientOnly>` 包裹或先判断 `isLoaded` 状态
环境变量未被识别	前缀错误	Nuxt要求公开环境变量前缀为 `NUXT_PUBLIC_` ，服务端环境变量前缀为 `NUXT_`

Org-Aware Pattern

组织权限适配模式

vue

<script setup lang="ts">
const { orgId, orgRole } = useAuth()
</script>

<template>
  <div v-if="orgId">
    <p>Org: {{ orgId }}</p>
    <p v-if="orgRole === 'org:admin'">Admin panel</p>
  </div>
  <div v-else>
    <OrganizationSwitcher />
  </div>
</template>

vue

<script setup lang="ts">
const { orgId, orgRole } = useAuth()
</script>

<template>
  <div v-if="orgId">
    <p>组织ID：{{ orgId }}</p>
    <p v-if="orgRole === 'org:admin'">管理面板</p>
  </div>
  <div v-else>
    <OrganizationSwitcher />
  </div>
</template>

Docs

官方文档

Nuxt SDK