# nextjs 集成 ## 说明此技能为 Next.js 应用程序提供完整的 Clerk 身份验证集成，支持 App Router (Next.js 13+) 和 Pages Router 模式。它涵盖安装、中间件配置、身份验证帮助程序和受保护的路由模式。 ### 1\.文员安装和设置安装Clerk SDK并配置环境变量： # 运行自动安装脚本 bash ./skills/nextjs-integration/scripts/install-clerk.sh # 或者手动安装 npm 安装@clerk/nextjs **环境变量：** # 使用 Clerk 凭据创建 .env.local NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_your_key_here CLERK_SECRET_KEY=sk_test_your_key_here # 可选：自定义登录/注册 URL NEXT_PUBLIC_CLERK_SIGN_IN_URL=/登录 NEXT_PUBLIC_CLERK_SIGN_UP_URL=/注册 NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/仪表板 NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/onboarding **这有什么作用：** * 安装@clerk/nextjs 包 * 使用占位符键创建 .env.local * 配置登录/注册流程的重定向 URL * 设置身份验证端点 ### 2\.应用程序路由器集成为 Next.js App Router (13.4+) 配置 Clerk： # 运行 App Router 设置脚本 bash ./skills/nextjs-integration/scripts/setup-app-router.sh **创建的文件：** * `middleware.ts` \- 边缘路由保护 * `app/layout.tsx` \- ClerkProvider 包装器 * `app/sign-in/[[...sign-in]]/page.tsx` \- 登录页面 * `app/sign-up/[[...sign-up]]/page.tsx` \- 注册页面 **应用程序路由器功能：** * 具有 `auth()` 帮助器的服务器组件 * 带有 `useAuth()` 钩子的客户端组件 * 用于路由保护的边缘中间件 * 自动会话管理 * RSC兼容认证 **复制模板文件：** # 中间件配置 cp ./skills/nextjs-integration/templates/app-router/middleware.ts ./middleware.ts # 使用 ClerkProvider 的根布局 cp ./skills/nextjs-integration/templates/app-router/layout.tsx ./app/layout.tsx ### 3\.页面路由器集成为 Next.js 页面路由器配置 Clerk（12.x 及更早版本）： # 运行 Pages Router 设置脚本 bash ./skills/nextjs-integration/scripts/setup-pages-router.sh **创建的文件：** * `pages/_app.tsx` \- ClerkProvider 包装器 * `pages/api/auth.ts` \- 身份验证回调的 API 路由 * `pages/sign-in/[[...index]].tsx` \- 登录页面 * `pages/sign-up/[[...index]].tsx` \- 注册页面 **页面路由器功能：** * 带有身份验证的 getServerSideProps * 具有授权保护的API路由 * 客户端验证钩子 * 自定义登录/注册组件 **复制模板文件：** # _app.tsx 与 ClerkProvider cp ./skills/nextjs-integration/templates/pages-router/_app.tsx ./pages/_app.tsx # 认证API路由 cp ./skills/nextjs-integration/templates/pages-router/api/auth.ts ./pages/api/auth.ts ### 4\.认证中间件配置路由保护中间件： # 设置具有路由匹配的 auth 中间件 bash ./skills/nextjs-integration/scripts/configure-middleware.sh **中间件模式：** * 保护特定路由（例如`/dashboard/*`） * 公共路由配置 * API路由保护 * 自定义重定向逻辑 * 边缘运行时的匹配器配置 **中间件配置：** // middleware.ts - 保护边缘的路由从“@clerk/nextjs”导入{authMiddleware}；导出默认 authMiddleware({ 公共路由：[“/”，“/api/public”]，被忽略的路由：[“/ api / webhook”]， }); 导出常量配置= { 匹配器: ['/((?!.+\\.[\\w]+$|_next).*)', '/', '/(api|trpc)(.*)'], }; ### 5\.服务器组件身份验证（应用程序路由器）在服务器组件中使用 `auth()` 帮助器：从“@clerk/nextjs”导入{auth}；导出默认异步函数 DashboardPage() { const { userId } = auth(); if (!userId) { 重定向（'/登录'）； } // 受保护的服务器组件逻辑 const userData = 等待 fetchUserData(userId); return

欢迎{userData.name}

; } **服务器端助手：** * `auth()` \- 获取当前用户会话 * `currentUser()` \- 获取完整的用户对象 * `redirectToSignIn()` \- 重定向助手 * `clerkClient` \- 服务器端 Clerk API 客户端 ### 6\.客户端组件身份验证在客户端组件中使用 React hooks： '使用客户端'；从'@clerk/nextjs'导入{useAuth，useUser}；导出函数 UserProfile() { const { userId, isLoaded, isSignedIn } = useAuth(); const { 用户 } = useUser(); if (!isLoaded) return

正在加载...

; if (!isSignedIn) return

请登录

; 返回

Hello {user.firstName}

; } **客户端挂钩：** * `useAuth()` \- 身份验证状态 * `useUser()` \- 当前用户数据 * `useClerk()` \- Clerk 实例方法 * `useSignIn()` \- 登录流程控制 * `useSignUp()` \- 注册流程控制 ## 示例 ### 示例 1：完整的 App Router 设置 # 1.安装Clerk bash ./skills/nextjs-integration/scripts/install-clerk.sh # 2.配置应用路由器 bash ./skills/nextjs-integration/scripts/setup-app-router.sh # 3. 设置中间件 bash ./skills/nextjs-integration/scripts/configure-middleware.sh # 4. 复制保护路由示例 cp ./skills/nextjs-integration/examples/protected-route.tsx ./app/dashboard/page.tsx # 5.复制服务器组件验证示例 cp ./skills/nextjs-integration/examples/server-component-auth.tsx ./app/profile/page.tsx # 6.启动开发服务器 npm 运行开发 **结果：** 完全配置的 Next.js App Router 具有 Clerk 身份验证、受保护的路由和登录/注册页面 ### 示例 2：使用 API 路由的页面路由器 # 1.安装Clerk bash ./skills/nextjs-integration/scripts/install-clerk.sh # 2. 配置页面路由器 bash ./skills/nextjs-integration/scripts/setup-pages-router.sh # 3.复制API路由模板 cp ./skills/nextjs-integration/templates/pages-router/api/auth.ts ./pages/api/auth.ts # 4. 测试认证 npm 运行开发 **结果：** 具有 API 路由身份验证和自定义身份验证页面的页面路由器设置 ### 示例 3：多租户应用程序配置基于组织的身份验证： // 具有组织上下文的服务器组件从“@clerk/nextjs”导入{auth}；导出默认异步函数 TeamDashboard() { const { orgId, userId } = auth(); 如果 (!orgId) { return

请选择组织

; } const teamData = 等待 fetchTeamData(orgId); 返回 ; } **组织特点：** * 多租户支持 * 组织切换 * 基于角色的访问控制 * 团队成员管理 ### 示例 4：受保护的 API 路由 // 带身份验证的 App Router API 路由从“@clerk/nextjs”导入{auth}；从'next/server'导入{NextResponse}；导出异步函数 GET() { const { userId } = auth(); if (!userId) { return new NextResponse('未经授权', { status: 401 }); } const data = 等待 fetchProtectedData(userId); 返回 NextResponse.json(数据); } ## 要求 **依赖关系：** * `@clerk/nextjs` \- Clerk Next.js SDK * Next.js 12.0+（页面路由器）或 13.4+（应用程序路由器） *反应18+ * Node.js 18.17+ 或 20+ **文员帐号：** * Active Clerk 申请（提供免费套餐） * 仪表板中的可发布密钥和秘密密钥 * 在 Clerk 仪表板中配置登录/注册流程 **项目结构：** * Next.js 项目使用 `create-next-app` 初始化 * `app/` 目录（App Router）或 `pages/` 目录（Pages Router） * 推荐使用 TypeScript，但不是必需的 **环境变量：** * `.env.local` 用于本地开发 * 用于生产环境的 `.env.production` （切勿提交机密） * Vercel/部署平台环境变量配置 ## 安全最佳实践 **切勿对 API 密钥进行硬编码：** # ✅ 正确 - 使用环境变量 CLERK_SECRET_KEY=your_clerk_secret_key_here # ❌ 错误 - 切勿泄露秘密 const clerkSecret = "sk_test_abc123..." // 不要这样做 **保护敏感路线：** * 使用中间件进行边缘级保护 * 验证服务器组件中的身份验证 * 检查API路由中的身份验证 * 永远不要单独相信客户端身份验证 **安全 API 路由：** // 始终验证服务器端的身份验证 const { userId } = auth(); if (!userId) { return new NextResponse('未经授权', { status: 401 }); } **环境变量管理：** * 使用 `.env.local` 进行开发（git-ignored） * 将 `.env.example` 与占位符一起使用（安全提交） * 将生产密钥存储在部署平台中 * 定期轮换密钥 ## 应用程序路由器与页面路由器 **在以下情况下使用应用路由器：** * 构建新的 Next.js 13.4+ 应用程序 * 需要服务器组件以获得更好的性能 * 想要边缘中间件功能 * 需要流媒体和悬疑功能 **在以下情况下使用页面路由器：** * 维护现有的 Next.js 12.x 应用程序 * 团队熟悉传统的 Next.js 模式 * 需要 getServerSideProps/getStaticProps * 从较旧的 Next.js 版本逐步迁移 **迁移路径：** * 可以在同一应用程序中混合使用两个路由器 * 增量迁移路由 * 新功能推荐使用 App Router ## 集成模式 **与Supabase：** * 使用Clerk进行身份验证 * 将职员用户 ID 传递给 Supabase RLS 策略 * 在 Clerk 和 Supabase 之间同步用户数据 **使用 tRPC：** * 将 Clerk 用户上下文添加到 tRPC 上下文 * 使用auth中间件保护程序 * API层的类型安全认证 **使用 Prisma：** * 将职员用户 ID 存储为外键 * 将用户数据链接到职员资料 * 使用userId进行数据隔离 **与维塞尔：** * 自动环境变量同步 * 边缘中间件部署 * 通过身份验证预览部署 ## 故障排除 **中间件未运行：** * 检查 middleware.ts 中的匹配器配置 * 确保 middleware.ts 位于项目根目录 * 验证 Edge 运行时兼容性 **登录重定向循环：** * 检查 `NEXT_PUBLIC_CLERK_SIGN_IN_URL` 是否匹配路由 * 验证 publicRoutes 包含登录页面 * 确保中间件不保护身份验证路由 **服务器组件水合作用：** * 不要在服务器组件中使用 useAuth * 使用 auth() 辅助函数代替 * 确保 ClerkProvider 包裹布局 **环境变量未加载：** * .env 更改后重新启动开发服务器 * 对客户端变量使用 NEXT_PUBLIC_ 前缀 * 检查 .env.local 是否存在并且被 git 忽略 ** ** **插件：** clerk **版本：** 1.0.0 **类别：** 身份验证 **技能类型：** 集成和配置

Nextjs 集成

包含技能