mcpField
C
clerk-nuxt-patterns

clerk-nuxt-patterns

github.com/clerk开发8914.0k 次安装今天更新
代码仓库

关于 clerk-nuxt-patterns

面向 Nuxt 开发者的 Clerk 认证模式技能，涵盖路由保护、Nitro 服务端 API、组合式函数和 SSR 认证处理。

主要功能

  1. 01Nuxt 认证中间件模式
  2. 02Nitro 路由认证
  3. 03认证组合式函数用法
  4. 04SSR 水合处理
  5. 05组织角色模式

适用场景

  1. 01为页面添加登录保护
  2. 02在 Nitro API 路由检查身份
  3. 03在组件中读取用户状态
  4. 04处理 SSR 认证状态水合

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/clerk/skills --skill clerk-nuxt-patterns

安装后在 Claude Code 中输入/clerk-nuxt-patterns确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

evals/
evals.json
references/
composables.md
nuxt-middleware.md
server-api-routes.md
ssr-auth.md
templates/nuxt-basic-auth/
app.vue
nuxt.config.ts
package.json

详细介绍

Nuxt 模式

你需要什么？

任务参考
使用中间件保护路由references/nuxt-middleware.md
在服务器 API 路由中进行身份验证（Nitro）references/server-api-routes.md
在组件中使用 useAuth / useUserreferences/composables.md
SSR 安全的身份验证模式references/ssr-auth.md

参考

参考描述
references/nuxt-middleware.md路由保护，clerkMiddleware()
references/server-api-routes.mdNitro 服务器路由身份验证
references/composables.mduseAuth、useUser、useClerk
references/ssr-auth.mdSSR 水合、服务器端与客户端

设置

npm install @clerk/nuxt

.env：

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

nuxt.config.ts：

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

这一行会自动配置中间件、插件和组件自动导入。

心智模型

@clerk/nuxt 会自动导入所有 Clerk 组件和组合式函数——无需在 <script setup> 中显式导入。

  • 组合式函数（useAuth、useUser）——客户端响应式，仅在 <script setup> 中使用
  • 服务器路由（clerkClient）——Nitro 服务器路由，event.context.auth
  • 中间件（clerkMiddleware）——自动注册，使用 auth().protect() 锁定路由

最简模式


<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' }) 使用 @clerk/nuxt 内置的身份验证中间件。

常见问题

现象原因解决方法
组合式函数在服务器上返回 undefineduseAuth 仅适用于客户端在服务器路由中使用 event.context.auth
路由未受保护缺少 middleware: 'auth' 元信息添加 definePageMeta({ middleware: 'auth' })
clerkClient 不可用导入路径错误从 @clerk/nuxt/server 导入
水合不匹配在挂载前渲染身份验证状态使用 <ClientOnly> 包裹，或检查 isLoaded
未读取环境变量前缀错误Nuxt 要求公共变量使用 NUXT_PUBLIC_，服务器变量使用 NUXT_

组织感知模式

<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>

另请参阅

  • clerk-setup - Clerk 初始安装
  • clerk-custom-ui - 自定义流程与外观
  • clerk-orgs - B2B 组织

文档

Nuxt SDK

评论

支持 Markdown