在 Next.js 项目中用 Clerk…

适用于使用 Clerk 的 Next.js 应用：按服务端/客户端正确取鉴权信息，保护页面、API、Server Actions，并处理会话令牌、缓存和手动 JWT 验证。

适用场景

解决思路

1. 确保配置所需环境变量：`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` 和 `CLERK_SECRET_KEY`；若独立 API server 需手动 JWT 验证，还要配置 `CLERK_JWT_KEY` 或 `CLERK_PEM_PUBLIC_KEY`。
2. 查看 `package.json` 中的 SDK 版本，并参考 `clerk` skill 的版本表；遇到 `> **Core 2 ONLY (skip if current SDK):**` 标记时，仅 Core 2 项目才采用该差异做法。
3. 若只需要基础安装配置，参考 `clerk-setup` skill。
4. 需要 Server vs client auth（`auth()` vs hooks）时查阅 `references/server-vs-client.md`。
5. 需要配置 middleware（public-first vs protected-first）时查阅 `references/middleware-strategies.md`。
6. 需要保护 Server Actions 时查阅 `references/server-actions.md`。
7. 需要 API route auth（401 vs 403）时查阅 `references/api-routes.md`。
8. 需要缓存鉴权数据（user-scoped caching）时查阅 `references/caching-auth.md`。
9. 建立心智模型：Server 用 `await auth()`（来自 `@clerk/nextjs/server`，异步）；Client 用 `useAuth()` hook（来自 `@clerk/nextjs`，同步）。
10. 不要混用 Server 和 Client 的 auth API；Server Components 使用 server imports，Client Components 使用 hooks。
11. 从 `auth()` 读取关键属性：`isAuthenticated`（boolean，替代 `!!userId` 模式）、`sessionStatus`（`'active'` | `'pending'`，用于检测未完成 session tasks）、`userId`、`orgId`、`orgSlug`、`has()`、`protect()`。
12. Core 2 项目中 `isAuthenticated` 和 `sessionStatus` 不可用，改用检查 `!!userId`。
13. Server Component 最小模式：`import { auth } from '@clerk/nextjs/server'`；`const { isAuthenticated, userId } = await auth()` 必须 `await`；若 `!isAuthenticated` 返回未登录提示；否则渲染用户内容。
14. Core 2 最小模式：`isAuthenticated` 不可用，使用 `if (!userId)` 判断。
15. 客户端条件渲染使用 `<Show>`：`import { Show } from '@clerk/nextjs'`；`<Show>` 覆盖认证检查和授权（feature、plan、role、permission）。
16. 认证检查：`<Show when="signed-in" fallback={<p>Please sign in</p>}>`。
17. B2B feature 检查：`<Show when={{ feature: 'analytics' }} fallback={<UpgradePrompt />}>`；优先基于 feature，因为 feature 可在 plan 间移动而无需重新部署。
18. B2B permission 检查：`<Show when={{ permission: 'org:invoices:create' }}>`；优先于 role-based 以获得更细粒度访问控制。
19. Plan 层级门控：`<Show when={{ plan: 'pro' }}>`。
20. Role 检查少用：`<Show when={{ role: 'org:admin' }}>`。
21. 复杂逻辑用回调：`<Show when={(has) => has({ role: 'org:admin' }) || has({ role: 'org:billing_manager' })}>`。
22. Core 2 中 `<Show>` 不存在；认证用 `<SignedIn>` 和 `<SignedOut>`；授权（role/permission）用 `<Protect>` 并传相同 props：`role`、`permission`、`condition`；feature 和 plan 变体需要 Core 3；迁移表见 `clerk-custom-ui` skill、`core-3/show-component.md`。
23. 修复 Server Component 中 `userId` 为 `undefined`：使用 `await auth()` 而不是 `auth()`。
24. 修复 API routes 鉴权不生效：在 `proxy.ts` 中添加 matcher `'/(api|trpc)(.*)'`；Next.js <=15 使用 `middleware.ts`。
25. 修复缓存返回错误用户数据：在 `unstable_cache` key 中包含 `userId`。
26. 防止 mutations 绕过 auth：在 Server Action 开始处检查 `auth()`。
27. 正确选择 HTTP 错误码：401 = 未登录，403 = 无权限。
28. 用 `getToken()` 访问外部 API：在 Clerk dashboard 定义 JWT templates，将自定义 JWT 传给第三方服务（Hasura、Supabase 等）。
29. Server-side 获取外部 API token：在 Server Component 或 Route Handler 中 `const { getToken } = await auth()`；`const token = await getToken({ template: 'hasura' })`；若 `!token` 返回未认证；请求时设置 `headers: { Authorization: `Bearer ${token}` }`。
30. Client-side 获取外部 API token：在 Client Component 中 `'use client'`；`const { getToken } = useAuth()`；`const token = await getToken({ template: 'supabase' })`；若 `!token` 返回；请求时设置 `Authorization: Bearer ${token}`。
31. `getToken()` 在用户未认证时返回 `null`，使用前总是 null-check。
32. 用 `useSession()` 读取会话数据：在 client components 中 `'use client'`；`const { session } = useSession()`；若 `!session` 返回 `null`；渲染 `session.id` 和 `session.lastActiveAt.toISOString()`。
33. 在没有 Clerk middleware 的独立 API server 中手动验证 JWT：从 `Authorization` header 或同源 `__session` cookie 接收 Clerk session tokens。
34. 手动验证推荐用 `@clerk/backend` 的 `verifyToken`：`token = req.headers.authorization?.replace('Bearer ', '')`；若无 token 返回 401；`claims = await verifyToken(token, { jwtKey: process.env.CLERK_JWT_KEY })`；`claims.sub = userId`；失败返回 401 Invalid token。
35. 不能使用 `@clerk/backend` 时用 `jsonwebtoken`：`publicKey = process.env.CLERK_PEM_PUBLIC_KEY!.replace(/\\n/g, '\n')`；`token = req.headers.authorization?.replace('Bearer ', '')`；若无 token 返回 401；`jwt.verify(token, publicKey, { algorithms: ['RS256'] }) as jwt.JwtPayload`；手动检查 `exp` 和 `nbf`（`jsonwebtoken` 会自动做，但如有需要验证 `azp`）；`claims.sub = userId`；失败返回 401 Invalid or expired token。
36. Token 来源：同源请求用 `__session` cookie（Clerk 自动设置）；跨域、移动端或 API-to-API 用 `Authorization: Bearer <token>` header。
37. 手动 JWT 验证关键：总是检查 `exp` 和 `nbf` claims；`@clerk/backend` 的 `verifyToken` 自动处理；raw `jsonwebtoken` 设置 `ignoreExpiration: false`（默认），并确保 `clockTolerance` 最小。
38. 相关主题参考：初始 Clerk 安装看 `clerk-setup`；B2B patterns 看 `clerk-orgs`；plan 和 feature entitlements with `has()` 看 `clerk-billing`；同步 user/org events 到数据库看 `clerk-webhooks`；内置组件主题和定制看 `clerk-custom-ui`。
39. Next.js SDK 文档：https://clerk.com/docs/reference/nextjs/overview。

适用边界 · 注意事项

• 项目不使用 Clerk 或 Next.js 时不适用。
• 无法配置 Clerk 环境变量（`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`、`CLERK_SECRET_KEY`；手动 JWT 验证还需要 `CLERK_JWT_KEY` 或 `CLERK_PEM_PUBLIC_KEY`）时不适用。
• 只需要初始安装/基础设置而非高级模式时，应改用 `clerk-setup` skill。