# 使用 Supabase 实施 Next.js 使用“.claude/modules/nextjs-patterns.md”和“.claude/modules/supabase-security.md”中的模式实现功能的交互式指南。 ## 快速决策：服务器组件还是客户端组件？使用此决策树来选择正确的组件类型： **第 1 步：是否需要用户交互？** * onClick、onChange、onSubmit 处理程序？ * useState、useEffect 或其他 React hooks？ * 浏览器 API（localStorage、window）？ → **是** = 客户端组件（`'使用客户端'`）→ **否** = 继续步骤 2 **第 2 步：它是否从数据库/API 获取数据？** * Supabase 查询？ * 从外部API获取？ * 从数据库读取？ → **是** = 服务器组件（默认） → **否** = 服务器组件（默认，除非步骤 1 为“是”） ## 常见场景您正在构建什么 |组件类型 |超级数据库客户端 ---|---|--- 显示菜谱的页面 |服务器组件 | `@/lib/supabase/server` 保存/删除按钮 |客户端组件 | `@/lib/supabase/client` 带有验证的表单 |客户端组件 | `@/lib/supabase/client` 带有服务器操作的表单 |服务器组件 |使用服务器操作实时聊天 |客户端组件 | `@/lib/supabase/client` 带有数据的仪表板 |服务器组件 | `@/lib/supabase/server` API 路由处理程序 |服务器（路由处理程序）| `@/lib/supabase/server` ## 实现模式 ### 模式 1：具有数据获取功能的服务器组件 **何时：** 显示数据库中的数据 **文件位置：** `app/**/page.tsx` 或 `app/**/layout.tsx` // 应用程序/食谱/page.tsx 从 '@/lib/supabase/server' 导入 { createClient } 从“@/components/RecipeList”导入食谱列表导出默认异步函数 RecipesPage() { const supabase = 等待 createClient() // 获取服务器上的数据 const { 数据：食谱，错误 } = 等待 supabase .from('已保存的食谱') .select('*') // 处理错误如果（错误）{ return } // 将数据传递给组件返回 } **参见：** [nextjs-patterns.md]() ### 模式 2：具有交互性的客户端组件 **时间：** 用户交互、状态管理 **文件位置：** `components/**/*.tsx` // 组件/SaveButton.tsx “使用客户端” 从 '@/lib/supabase/client' 导入 { createClient } 从 'react' 导入 { useState } 导出默认函数 SaveButton({recipeId }: {recipeId: string }) { const [保存，setSaving] = useState(false) const supabase = createClient() const handleSave = async () => { 设置保存（真） const { 错误 } = 等待 supabase .from('已保存的食谱') .insert({ id:recipeId }) 如果（错误）{ console.error('保存失败：', error) } 设置保存（假） } 返回（ <按钮 onClick={handleSave} 禁用={保存}> {节省？ '保存...' : '保存食谱'} ） } **参见：** [nextjs-patterns.md]() ### 模式 3：服务器组件 → 客户端组件（数据流） **何时：** 需要将服务器数据传递给交互组件 **规则：** 只传递必填字段，从不传递完整对象 // app/profile/page.tsx（服务器组件）从 '@/lib/supabase/server' 导入 { createClient } import ProfileEditor from '@/components/ProfileEditor' // 客户端组件导出默认异步函数 ProfilePage() { const supabase = 等待 createClient() const { data: { user } } =等待supabase.auth.getUser() 如果（！用户）{ 重定向（'/登录'） } // ✅ 正确：仅传递必填字段返回（ <个人资料编辑器 userId={用户.id} 电子邮件={用户.电子邮件} 名称={user.user_metadata?.name} /> ） // ❌ 错误：不要传递完整的用户对象（安全风险） // 返回 } **参见：** [supabase-security.md]() ### 模式 4：突变的服务器操作 **时间：**表单提交、数据突变 **文件位置：** `app/actions.ts` 或与页面位于同一位置 // 应用程序/actions.ts '使用服务器' 从 '@/lib/supabase/server' 导入 { createClient } 从 'next/cache' 导入 { revalidatePath } 导出异步函数 saveRecipe(formData: FormData) { const supabase = 等待 createClient() // 验证用户 const { data: { user } } =等待supabase.auth.getUser() 如果（！用户）{ 返回 { 错误：'未经授权'} } // 提取表单数据 const name = formData.get('name') 作为字符串 const 成分 = formData.get('成分') 作为字符串 // 执行变异 const { 错误 } = 等待 supabase .from('已保存的食谱') .insert({ 名称, 成分, user_id: user.id }) 如果（错误）{ 返回 { 错误：错误.消息 } } // 重新验证缓存 revalidatePath('/食谱') 返回 { 成功：真 } } **参见：** [nextjs-patterns.md]() ## 哪个 Supabase 客户端？ **关键规则：** 使用适合环境的正确客户端。环境 |进口|用途 ---|---|--- 服务器组件 | `从'@/lib/supabase/server'导入{createClient}` | `const supabase = 等待 createClient()` 客户端组件 | `从'@/lib/supabase/client'导入{createClient}` | `const supabase = createClient()` 服务器操作 | `从'@/lib/supabase/server'导入{createClient}` | `const supabase = 等待 createClient()` 路线处理程序 | `从'@/lib/supabase/server'导入{createClient}` | `const supabase = 等待 createClient()` 中间件| `从'@/lib/supabase/middleware'导入{createClient}` | `const { supabase } = createClient(请求)` **参见：** [supabase-security.md]() ## 安全检查表实施之前，请验证： * 使用正确的 Supabase 客户端环境？ * 用于获取数据的服务器组件（不是客户端）？ * 只将必填字段传递给客户端组件？ * 使用 `getUser()` 而不是 `getSession()` 进行身份验证？ * 没有敏感数据暴露给客户？ * 考虑数据访问的 RLS 策略？ **参见：** [supabase-security.md]() ## 要避免的常见错误 ❌ 错误 | ✅修复 ---|--- 异步客户端组件 |使用服务器组件或`useEffect` Supabase 客户端错误 |检查上面的表格传递完整的用户对象 |仅传递需要的字段 “任何”类型 |使用 lib/supabase/types.ts 中的特定类型无错误处理|始终检查是否有错误缺少加载状态 |显示旋转器/骨架 **参见：** [anti-patterns.md]() ## 🔄 工作流程 > **Kaynak：** [Supabase SSR 指南 (Next.js)]() & [Next.js 15 应用路由器安全]() ### Aşama 1：环境和客户端初始化 * **客户端选择** : 可以选择 `@supabase/ssr` kullanarak 服务器客户端 (RSC/Actions) veya 浏览器客户端 (RCC) başlat。 * **中间件防护**：RLS（行级安全性）ek olarak，中间件控制会话刷新mekanizmasını kur。 * **类型映射** ：`database.types.ts` dosyasını otomatik 生成和 Supabase 实例'ına enjekte 等。 ### Aşama 2：数据编排 * **服务器端获取** ：Veriyi en üst seviyede（页面/布局）服务器组件的最小真实性。 * **服务器操作** ：在“使用服务器”直接修改“revalidatePath”文件缓存中的表单突变。 * **RLS 审核**：Veritabanı seviyesinde `auth.uid()` bazlı politikaların tüm tablolar için (SELECT/INSERT/UPDATE) aktif olduğunu doğrula。 ### Aşama 3：安全与实时操作 * **Auth Validation** : `getSession()` yerine her zaman daha güvenli olan `getUser()` metodunu tercih et. * **实时处理** ：通过`supabase.channel()` 和订阅'ları kur ve temizle (`unmount`) 来实现。 * **Edge Functions** : Yoğun işlem gerektiren veya 3.parti API entegrasyonu (örn: Stripe/SendGrid) için Edge Functions kullan。 ### 控制Noktaları 阿萨马 |多鲁拉马 ---|--- 1 |服务角色密钥 asla 客户端 kodda (RCC) kullanılıyor mu？ 2 |提交表单时“Optimistic UI”是怎样的？ 3 | `process.env` verileri 是本地的 üretim（Supabase Dashboard）还是 tamında uyumlu mu？ ** ** _Supabase 模式 v2.0 - 带工作流程_ ## 获取帮助有关详细模式和示例： * **Next.js 模式：** 请参阅 [nextjs-patterns.md]() * **Supabase 安全性：** 请参阅 [supabase-security.md]() * **TypeScript 类型：** 请参阅 [typescript-standards.md]() * **不要做什么：** 请参阅 [anti-patterns.md]() ## 快速参考 **服务器组件模板：** 从 '@/lib/supabase/server' 导入 { createClient } 导出默认异步函数 Page() { const supabase = 等待 createClient() const { data, error } = wait supabase.from('table').select('*') 如果（错误）返回<错误/> 返回 <组件数据={data} /> } **客户端组件模板：** “使用客户端” 从 '@/lib/supabase/client' 导入 { createClient } 从 'react' 导入 { useState } 导出默认函数 Component() { const [状态，setState] = useState() const supabase = createClient() // 你的交互逻辑返回

...

} **服务器操作模板：** '使用服务器' 从 '@/lib/supabase/server' 导入 { createClient } 从 'next/cache' 导入 { revalidatePath } 导出异步函数操作（formData：FormData）{ const supabase = 等待 createClient() const { data: { user } } =等待supabase.auth.getUser() if (!user) return { error: '未经授权' } // 变异逻辑重新验证路径（'/路径'）返回 { 成功：真 } }

Supabase 模式

包含技能