clerk-nextjs-patterns 是一套关于在 Next.js 中使用 Clerk 的进阶模式参考，侧重中间件、Server Actions 以及与认证相关的缓存处理。资料说明基础配置可参见 setup/ 目录，本条目主要面向进阶用法与易错点。
用途与定位 该资料以“影响等级”组织内容，帮助开发者识别风险优先级：
- CRITICAL：会导致破坏性 bug 或安全漏洞的问题。
- HIGH：常见错误。
- MEDIUM：优化类问题。
参考文件与影响等级
- references/server-vs-client.md：CRITICAL，涉及 await auth() 与 hooks 的区别。
- references/middleware-strategies.md：HIGH，涉及“公开优先”与“保护优先”两种策略。
- references/server-actions.md：HIGH，涉及保护变更操作（mutations）。
- references/api-routes.md：HIGH，涉及 401 与 403 的区分。
- references/caching-auth.md：MEDIUM，涉及按用户作用域的缓存。
核心心智模型 服务端与客户端使用不同的认证 API：
- 服务端：从 @clerk/nextjs/server 导入 await auth()，是异步的。
- 客户端：使用来自 @clerk/nextjs 的 useAuth() hook，是同步的。 资料强调两者绝不能混用：Server Components 使用服务端导入，Client Components 使用 hooks。
最小模式示例 // Server Component import { auth } from '@clerk/nextjs/server'
export default async function Page() { const { userId } = await auth() // MUST await! if (!userId) return <p>Not signed in</p> return <p>Hello {userId}</p> }
常见陷阱对照
- 症状：Server Component 中 userId 为 undefined；原因：缺少 await；修复：使用 await auth() 而非 auth()。
- 症状：API 路由上认证不生效；原因：缺少 matcher；修复：添加
'/(api（资料原文如此）。 - 症状：缓存返回错误用户的数据；原因：key 中缺少 userId；修复：在 unstable_cache key 中包含 userId。
- 症状：变更操作绕过认证；原因：Server Action 未受保护；修复：在 action 开始处检查 auth()。
- 症状：HTTP 错误码错误；原因：混淆 401/403；修复：401 表示未登录，403 表示无权限。
相关条目 资料还列出 See Also：setup/、managing-orgs/，以及 Docs：Next.js SDK。
适用场景与限制 该资料适用于需要在 Next.js 中正确、安全地集成 Clerk 认证并避免常见错误的开发者。其内容以模式与陷阱说明为主，未提供具体的安装命令、版本要求、收费或价格信息；这些事实在现有资料中暂未提供。