1. 项目概述一个由AI驱动的智能菜谱生成器最近在捣鼓一些AI应用落地的项目发现了一个挺有意思的开源项目——Chef Genie。简单来说这就是一个“AI大厨”你告诉它你冰箱里有什么、想吃什么口味、有什么忌口它就能给你生成一份像模像样的菜谱。项目本身基于Next.js 14构建集成了OpenAI、Supabase、Clerk等一堆现代Web开发的热门技术栈非常适合想学习如何将这些技术组合起来打造一个完整AI应用的开发者。我自己也尝试部署和魔改了一下发现它不仅仅是一个玩具。从技术选型到实现细节都体现了当前全栈开发的一些最佳实践。比如用Next.js 14的Server Actions处理AI请求用Clerk做无痛身份验证用Supabase管理用户数据和生成的菜谱。整个流程跑下来对理解如何构建一个数据驱动、用户友好的AI交互应用很有帮助。无论你是想学习Next.js全栈开发还是想了解如何将ChatGPT API集成到自己的产品中这个项目都是一个不错的起点。2. 技术栈深度解析与选型考量2.1 核心框架为什么是Next.js 14 App Router项目选择了Next.js 14并且明确使用了App Router模式这几乎是2024年新建React项目的默认选择了。App Router带来的最大改变是基于文件系统的路由和**服务端组件Server Components**的默认支持。对于Chef Genie这样的AI应用来说使用Server Components和Server Actions有天然优势。生成菜谱是一个需要调用OpenAI API的“慢操作”如果放在客户端不仅会暴露API密钥虽然可以通过代理但增加了复杂性还会因为网络延迟导致用户体验不佳。通过Server Action我们可以在服务端安全地调用AI接口并将生成的流式结果逐步推送到客户端。这意味着用户提交请求后能看到菜谱标题、食材、步骤一条条“流式”地出现而不是对着一个空白页面干等体验提升非常明显。另一个关键点是SEO和性能。菜谱生成页面如果被分享其内容生成的菜谱是希望被搜索引擎收录的。使用Server Components可以在构建时或请求时生成完整的HTML对搜索引擎友好。同时Next.js内置的图片优化、字体优化、脚本加载策略都为这个可能包含大量文本和图片未来扩展的应用提供了性能保障。注意从Pages Router迁移到App Router需要一定的学习成本尤其是数据获取、缓存和渲染策略的理解。但长远来看拥抱App Router是更优解其开发模式更统一功能也更强大。2.2 AI集成Vercel AI SDK的价值所在项目没有直接裸调OpenAI的Node.js SDK而是引入了Vercel AI SDK。这是一个明智的选择它不是一个“套壳”而是一个强大的抽象层。首先它提供了统一的流式响应Streaming处理。OpenAI的Chat Completion API支持以流的形式返回tokenVercel AI SDK的streamText函数让处理这种流式响应变得异常简单几行代码就能在Next.js的Server Action中实现并配合useChat等React Hook在前端实时渲染。如果你自己手动处理分块解码、状态管理会麻烦很多。其次它带来了多模型支持的可能性。虽然当前项目只用了GPT-3.5 Turbo但AI SDK的接口设计是模型无关的。这意味着如果你未来想换成Anthropic的Claude、Google的Gemini甚至本地部署的Ollama模型只需要更换配置和调用函数业务逻辑代码改动可以降到最低。这种可移植性对于长期维护的项目至关重要。最后它内置了一些实用工具比如计算Token数量对于控制成本很有用、处理AI消息的历史记录等。这些工具函数能避免重复造轮子让开发者更专注于提示工程和业务逻辑。2.3 数据层与身份验证Supabase Clerk的组合拳为什么选择Supabase而不是独立的PostgreSQL数据库加自研API对于这样一个起步项目开发速度和一体化体验是关键。Supabase提供了开箱即用的实时数据库、身份认证、存储和边缘函数其与PostgreSQL的深度绑定意味着你可以用标准的SQL操作数据同时享受BaaS后端即服务的便利。在Chef Genie中Supabase很可能用于存储用户生成的菜谱历史、收藏夹或者用户自定义的食材偏好。通过Row Level SecurityRLS可以方便地实现数据隔离确保用户只能访问自己的数据。其JavaScript/TypeScript客户端库非常易用与Next.js的Server Components和Server Actions能很好地配合。身份验证则交给了Clerk。这是一个专门做开发者体验的Auth服务。它的优势在于提供了预构建的、可定制的UI组件如SignInButton /,UserButton /以及完整的用户管理后台。集成Clerk通常只需要几行代码就能获得邮箱/密码、社交登录Google, GitHub等、多因素认证等全套功能。对于个人开发者或小团队使用Clerk或类似服务如Auth.js远比从头实现一套安全、稳定的认证系统要高效、安全得多。这个组合Supabase Clerk实际上形成了一种“后端即服务”的架构让前端开发者能够快速构建出功能完整的全栈应用而无需深入后端基础设施的运维。2.4 UI与样式从Tailwind CSS到shadcn/ui的演进技术栈中UI部分的选择非常具有代表性Tailwind CSS Radix UI shadcn/ui。Tailwind CSS是实用优先的CSS框架它通过提供大量原子类来加速UI开发。在Chef Genie这样的项目中它能确保样式的高度定制化和一致性同时避免了传统CSS可能出现的类名冲突和样式臃肿问题。Radix UI是一个“无头”HeadlessUI组件库。它不提供任何样式只提供完全无障碍、功能完备的交互逻辑和组件状态管理。例如一个下拉菜单Dropdown的打开/关闭状态、焦点管理、键盘导航等复杂交互Radix UI都帮你处理好了。开发者需要自己用Tailwind CSS来给它“穿衣服”添加样式。这带来了极大的样式自由度和可控性。shadcn/ui正是基于上述两者理念的产物。它不是一个通过npm install安装的组件库而是一套你可以复制粘贴到自己项目中的高质量组件代码。这些组件使用Radix UI作为功能基座用Tailwind CSS编写样式。你可以完全控制这些组件的源代码并根据项目需求进行任意修改。这对于需要品牌定制化但又不想从零开始造轮子的项目来说是完美的选择。Chef Genie采用它既能获得美观、一致的UI又能保持技术的纯粹性和可维护性。3. 项目本地运行与核心配置详解3.1 环境准备与依赖安装要运行这个项目你需要一个相对现代的Node.js环境建议18.17或更高版本。项目使用pnpm作为包管理器这比传统的npm或yarn在安装速度和磁盘空间利用上更有优势。如果你没有安装pnpm可以通过npm install -g pnpm快速安装。第一步是克隆代码并安装依赖这看起来简单但有几个细节需要注意git clone https://github.com/giacomogaglione/chef-genie.git cd chef-genie pnpm install执行pnpm install时它会读取package.json和pnpm-lock.yaml确保安装的依赖版本与作者锁定的版本完全一致。这能最大程度避免“在我机器上是好的”这类问题。如果安装过程中出现网络问题可以尝试配置淘宝镜像源或使用科学的上网方式此处指代合规的网络加速服务需用户自行合法解决。3.2 环境变量配置项目的命脉这是最关键的一步所有第三方服务的接入都依赖于此。项目提供了一个.env.example文件作为模板。cp .env.example .env接下来你需要用文本编辑器打开新创建的.env文件并逐一填写以下关键变量OpenAI API Key (OPENAI_API_KEY)作用调用GPT模型生成菜谱的核心凭证。获取前往 OpenAI平台 注册登录创建新的API Key。注意新账号通常有免费额度但生成菜谱这类文本任务消耗token需关注用量和成本。安全警告此密钥绝不能提交到Git仓库。.env文件已被项目.gitignore排除请务必确认。Clerk密钥 (NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY,CLERK_SECRET_KEY)作用用于前端展示登录组件和后端验证用户身份。获取在 Clerk仪表板 创建新应用后在“API Keys”页面即可找到这两组密钥。NEXT_PUBLIC_前缀的变量意味着它可以在客户端代码中被访问而CLERK_SECRET_KEY仅用于服务端。Supabase连接信息 (NEXT_PUBLIC_SUPABASE_URL,NEXT_PUBLIC_SUPABASE_ANON_KEY,SUPABASE_SERVICE_ROLE_KEY)作用连接你的Supabase项目数据库。获取在 Supabase控制台 创建新项目后进入项目设置Settings - API页面。Project URL就是NEXT_PUBLIC_SUPABASE_URLanonpublic密钥就是NEXT_PUBLIC_SUPABASE_ANON_KEY。SUPABASE_SERVICE_ROLE_KEY是service_role密钥拥有绕过RLS的权限必须妥善保管仅用于服务端。配置延伸你还需要在Supabase中根据项目SQL文件如果提供创建数据表或者根据项目代码中的类型定义来设计表结构。通常你需要一个recipes表来存储生成的菜谱字段可能包括id,user_id关联Clerk用户ID,title,ingredients,instructions,created_at等。Vercel Analytics (VERCEL_ANALYTICS_ID)作用如果你将项目部署到Vercel并启用了Analytics功能可以在此配置ID以收集页面访问数据。本地开发时可留空或使用假值。实操心得建议在填写前先在对应的服务平台OpenAI, Clerk, Supabase完成账号注册和项目创建形成一个清晰的配置清单。一个常见的错误是复制密钥时多出空格或换行符导致连接失败。如果运行时出现认证错误第一件事就是检查.env文件中的值是否完全正确。3.3 启动开发服务器与初步验证配置完成后运行开发命令pnpm run dev如果一切顺利终端会输出类似“Ready on http://localhost:3000”的信息。此时在浏览器打开http://localhost:3000你应该能看到应用界面。首先测试的是身份验证流程。点击登录/注册按钮应该能跳转到Clerk提供的托管认证页面。成功注册或登录后会被重定向回应用并且UI上会显示你的用户头像或邮箱。这一步验证了Clerk集成是成功的。接下来测试核心的AI功能。在输入框中尝试输入一些食材比如“西红柿鸡蛋盐”选择“中式”口味点击生成。此时观察两个方面网络请求打开浏览器开发者工具的“网络”Network选项卡你应该能看到一个向/api或类似本地端点发出的请求并且响应类型可能是“text/event-stream”这表明流式响应在工作。界面反馈菜谱应该以逐字或逐段的形式显示出来而不是整个页面卡住后一次性弹出。如果这两步都成功了恭喜你项目的核心链路已经跑通。如果失败请根据终端和浏览器控制台的错误信息进行排查最常见的问题依然是环境变量配置错误或第三方服务如OpenAI的额度用尽。4. 核心功能实现与代码剖析4.1 AI菜谱生成提示工程与流式响应项目的核心灵魂在于如何与GPT对话让它扮演一个厨师。这不仅仅是一个简单的API调用而是涉及提示工程Prompt Engineering。在代码中你可能会找到一个类似这样的提示词模板const prompt 你是一位专业且富有创造力的厨师。请根据用户提供的食材、菜系偏好和饮食限制生成一份详细的菜谱。 请严格按照以下JSON格式回应不要包含任何其他解释 { title: 菜谱名称, description: 一段吸引人的简短描述, ingredients: [食材1及用量, 食材2及用量, ...], instructions: [步骤1, 步骤2, ...], tips: 一些烹饪小贴士 } 用户输入 食材${ingredients} 菜系偏好${cuisine} 饮食限制${restrictions} ;这个提示词做了几件关键事设定角色让AI进入“专业厨师”的语境。明确指令要求生成“详细的菜谱”。结构化输出强制要求以特定JSON格式回应这极大简化了后端处理逻辑。前端可以直接将流式响应的最终结果解析为JavaScript对象方便渲染。注入变量将用户输入的食材、口味等动态插入提示词中。在Server Action中调用Vercel AI SDK的流程大致如下import { streamText } from ai; import { openai } from ai-sdk/openai; export async function generateRecipe(ingredients: string, cuisine: string) { use server; // Next.js Server Action标记 const result streamText({ model: openai(gpt-3.5-turbo), // 指定模型 prompt: prompt, // 上面构建的提示词 temperature: 0.7, // 控制创造性0.7是一个平衡值 }); // 将AI SDK的流式响应转换为Next.js可用的流 return result.toDataStreamResponse(); }前端则使用useChatHook来连接这个Server Action并实时更新UIimport { useChat } from ai/react; export function RecipeForm() { const { messages, input, handleInputChange, handleSubmit, isLoading } useChat({ api: /api/recipe, // 指向你的Server Action路由 }); // messages数组会随着流式响应的推进自动更新 // 你可以遍历messages将最后一条AI回复的内容解析为JSON并渲染 }这种模式清晰地将AI逻辑隔离在服务端前端只负责展示和交互是构建AI应用的推荐架构。4.2 用户数据持久化与Supabase的交互生成菜谱后用户很可能希望保存它。这就涉及到将数据存入Supabase。通常在生成菜谱的Server Action中或生成完成后前端发起一个保存请求。首先你需要确保Supabase客户端在服务端和客户端都能正确初始化。项目通常会有一个lib/supabase.ts文件import { createClient } from supabase/supabase-js; const supabaseUrl process.env.NEXT_PUBLIC_SUPABASE_URL!; const supabaseAnonKey process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!; export const supabase createClient(supabaseUrl, supabaseAnonKey);在Server Action中保存菜谱时你需要使用服务端Supabase客户端并传入SUPABASE_SERVICE_ROLE_KEY以获得足够权限或者利用从Clerk获取的当前用户ID结合Supabase的RLS策略进行安全插入。假设有一个recipes表其RLS策略允许认证用户插入自己的数据CREATE POLICY Users can insert their own recipes ON recipes FOR INSERT TO authenticated WITH CHECK (auth.uid() user_id);那么在Server Action中保存逻辑可能如下import { supabaseServer } from /lib/supabase-server; // 使用服务端密钥初始化的客户端 import { auth } from clerk/nextjs/server; export async function saveRecipe(recipeData: any) { use server; const { userId } auth(); // 从Clerk获取当前用户ID if (!userId) throw new Error(未认证); const { error } await supabaseServer .from(recipes) .insert({ user_id: userId, title: recipeData.title, ingredients: recipeData.ingredients, instructions: recipeData.instructions, // ... 其他字段 }); if (error) throw error; return { success: true }; }前端则可以调用这个Server Action并处理成功或错误状态。这样一个完整的“生成-保存”闭环就实现了。4.3 前端状态管理与UI交互对于这样一个交互相对集中的应用状态管理并不复杂。React的useState、useEffect配合Server Actions和useChatHook基本够用。一个典型的页面状态可能包括inputIngredients: 用户输入的食材字符串。selectedCuisine: 选择的菜系。isGenerating: 是否正在生成菜谱来自useChat的isLoading。generatedRecipe: 解析后的菜谱对象。savedRecipes: 从Supabase获取的用户已保存菜谱列表。UI交互的重点在于良好的反馈。当用户点击“生成”时按钮应变为禁用状态并显示加载指示器如旋转图标。使用useChatHook提供的流式响应菜谱内容应逐行或逐段出现可以加入一个打字机效果Typewriter Effect的组件来提升体验。对于保存功能成功或失败应有即时的Toast通知。可以使用react-hot-toast或sonner与shadcn/ui风格很搭这样的轻量库来实现。5. 部署指南与生产环境考量5.1 部署到Vercel由于项目本身就是为Vercel优化的部署过程非常顺畅。推送代码到Git仓库将你的代码注意不要包含.env文件推送到GitHub、GitLab或Bitbucket。在Vercel导入项目登录 Vercel 点击“Add New” - “Project”选择你刚推送的仓库。配置环境变量在项目设置的“Environment Variables”页面将你在本地.env文件中配置的所有变量一一添加进去。这是最关键的一步确保生产环境能正确连接所有服务。部署Vercel会自动检测到这是Next.js项目并配置好构建命令和输出目录。点击“Deploy”即可。部署后Vercel会为你生成一个生产环境的URL如chef-genie.vercel.app。你可以访问这个链接测试生产环境下的认证、AI生成和数据库功能是否全部正常。5.2 生产环境优化与安全加固将开发项目变为可用的生产应用还需要一些额外步骤自定义域名与SSL在Vercel项目设置中可以绑定你自己的域名并自动配置免费的SSL证书。Clerk生产实例在Clerk仪表板中将你的应用环境从“开发”切换到“生产”。你需要为生产环境配置允许的回调URL即你的Vercel生产域名。生产环境下的密钥与开发环境不同记得在Vercel环境变量中更新。Supabase生产数据库Supabase的免费计划足够支撑小规模使用。确保生产环境连接的是Supabase生产项目的URL和密钥。考虑为生产数据库建立单独的连接并与开发数据隔离。OpenAI API成本与限额在OpenAI平台为生产环境的API Key设置使用限额Spending Limits防止意外超支。同时考虑对用户进行限流Rate Limiting例如每个用户每小时只能生成有限次数的菜谱这可以在Next.js的Server Action中通过检查数据库记录来实现。错误监控与日志集成像Sentry或Logtail这样的服务监控运行时错误和性能。Vercel自身也提供函数日志和Analytics。内容安全策略CSP由于涉及AI生成内容建议配置严格的CSP头防止XSS攻击。Next.js可以通过next.config.js中的headers函数进行配置。5.3 性能与扩展性思考当前架构对于中小流量已经足够。如果用户量增长可以考虑以下方向AI响应缓存相同的食材和偏好组合可能会生成相同或相似的菜谱。可以在Server Action中引入缓存层如使用Vercel KV、Upstash Redis或直接在Supabase中缓存结果对请求参数进行哈希短时间内相同的请求直接返回缓存结果大幅降低OpenAI API调用成本和响应时间。数据库索引优化如果recipes表数据量变大频繁按user_id或created_at查询务必在相应字段上创建数据库索引。静态资源优化未来如果添加菜谱图片应使用Next.js的Image /组件进行自动优化并考虑将图片存储到Supabase Storage或Vercel Blob中。6. 常见问题排查与调试技巧在实际运行和魔改过程中你肯定会遇到各种问题。这里记录一些典型问题的排查思路。6.1 环境变量相关错误症状应用启动失败或功能登录、AI生成不可用控制台报错“Missing API Key”或“Invalid Supabase URL”。排查本地确认.env文件在项目根目录且变量名与代码中process.env.XXX引用的完全一致注意大小写。重启开发服务器pnpm dev。Vercel生产环境登录Vercel控制台进入项目设置 - Environment Variables逐一核对所有变量是否已添加且值正确。特别注意密钥中是否有意外空格。修改后需要触发重新部署。6.2 AI生成失败或响应慢症状点击生成后无反应或等待很久后报错。排查OpenAI额度首先检查OpenAI平台账户的额度是否用尽或过期。网络问题Server Action调用OpenAI API受服务器网络影响。如果部署在Vercel其服务器全球分布通常网络良好。本地开发时不稳定的网络可能导致超时。提示词与参数检查传递给AI的提示词是否过长或格式错误。过高的temperature参数可能导致生成时间变长。尝试将temperature调低至0.5或设置max_tokens限制生成长度。流式响应中断检查前端useChat配置和后端Server Action的流式返回逻辑。确保没有在流结束前过早关闭连接。6.3 身份验证问题症状无法登录/注册或登录后用户状态不持久。排查Clerk密钥确认NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY和CLERK_SECRET_KEY配对正确且来自同一Clerk应用实例。回调URL在Clerk仪表板的“Redirects”设置中确保添加了你的应用地址本地开发是http://localhost:3000生产环境是你的Vercel域名到“Allowed redirect URLs”和“Allowed callback URLs”。中间件配置Next.js项目通常有一个middleware.ts文件来处理Clerk认证。检查其matcher配置确保需要保护的页面路由被正确覆盖。6.4 数据库操作失败症状保存菜谱失败前端报“RLS policy violation”或“insert error”。排查RLS策略登录Supabase控制台进入“Authentication” - “Policies”检查recipes表的INSERT策略是否已正确创建并启用。确保策略中的auth.uid()能与Clerk的用户ID对应上。有时需要创建一个自定义函数来将Clerk的userId映射到Supabase的auth.users表。用户ID映射这是一个常见痛点。Clerk的用户ID与Supabase内置的auth.users表的ID不同。常见的做法是在用户首次登录时在一个自定义的profiles表或直接在你的recipes表中将Clerk的userId存储为一个字段如clerk_user_id。然后你的RLS策略需要基于这个自定义字段进行校验而不是auth.uid()。或者使用Clerk的Webhooks在用户注册时在Supabase的auth.users表中创建一条对应记录但这更复杂。表结构确认你插入的数据字段名、类型与数据库表定义完全一致。6.5 样式或组件显示异常症状页面布局错乱或shadcn/ui组件无法交互。排查Tailwind CSS类名冲突检查是否在全局CSS或组件中引入了其他可能冲突的样式库。Radix UI Provider缺失许多Radix UI组件需要被对应的Provider包裹如ToastProvider,DialogProvider。检查应用的根布局app/layout.tsx是否包含了必要的Provider。CSS变量未定义shadcn/ui的样式依赖于一套CSS变量如--background,--foreground。检查app/globals.css中是否引入了主题CSS文件并正确定义了这些变量。调试时养成习惯首先查看浏览器开发者控制台的“Console”和“Network”选项卡这里通常有最直接的错误信息。对于服务端错误查看Vercel部署日志或本地终端输出。对于数据库问题Supabase控制台的“SQL Editor”和“Table Editor”是验证数据和SQL语句的好帮手。
基于Next.js 14与AI SDK构建智能菜谱生成器全栈实践
1. 项目概述一个由AI驱动的智能菜谱生成器最近在捣鼓一些AI应用落地的项目发现了一个挺有意思的开源项目——Chef Genie。简单来说这就是一个“AI大厨”你告诉它你冰箱里有什么、想吃什么口味、有什么忌口它就能给你生成一份像模像样的菜谱。项目本身基于Next.js 14构建集成了OpenAI、Supabase、Clerk等一堆现代Web开发的热门技术栈非常适合想学习如何将这些技术组合起来打造一个完整AI应用的开发者。我自己也尝试部署和魔改了一下发现它不仅仅是一个玩具。从技术选型到实现细节都体现了当前全栈开发的一些最佳实践。比如用Next.js 14的Server Actions处理AI请求用Clerk做无痛身份验证用Supabase管理用户数据和生成的菜谱。整个流程跑下来对理解如何构建一个数据驱动、用户友好的AI交互应用很有帮助。无论你是想学习Next.js全栈开发还是想了解如何将ChatGPT API集成到自己的产品中这个项目都是一个不错的起点。2. 技术栈深度解析与选型考量2.1 核心框架为什么是Next.js 14 App Router项目选择了Next.js 14并且明确使用了App Router模式这几乎是2024年新建React项目的默认选择了。App Router带来的最大改变是基于文件系统的路由和**服务端组件Server Components**的默认支持。对于Chef Genie这样的AI应用来说使用Server Components和Server Actions有天然优势。生成菜谱是一个需要调用OpenAI API的“慢操作”如果放在客户端不仅会暴露API密钥虽然可以通过代理但增加了复杂性还会因为网络延迟导致用户体验不佳。通过Server Action我们可以在服务端安全地调用AI接口并将生成的流式结果逐步推送到客户端。这意味着用户提交请求后能看到菜谱标题、食材、步骤一条条“流式”地出现而不是对着一个空白页面干等体验提升非常明显。另一个关键点是SEO和性能。菜谱生成页面如果被分享其内容生成的菜谱是希望被搜索引擎收录的。使用Server Components可以在构建时或请求时生成完整的HTML对搜索引擎友好。同时Next.js内置的图片优化、字体优化、脚本加载策略都为这个可能包含大量文本和图片未来扩展的应用提供了性能保障。注意从Pages Router迁移到App Router需要一定的学习成本尤其是数据获取、缓存和渲染策略的理解。但长远来看拥抱App Router是更优解其开发模式更统一功能也更强大。2.2 AI集成Vercel AI SDK的价值所在项目没有直接裸调OpenAI的Node.js SDK而是引入了Vercel AI SDK。这是一个明智的选择它不是一个“套壳”而是一个强大的抽象层。首先它提供了统一的流式响应Streaming处理。OpenAI的Chat Completion API支持以流的形式返回tokenVercel AI SDK的streamText函数让处理这种流式响应变得异常简单几行代码就能在Next.js的Server Action中实现并配合useChat等React Hook在前端实时渲染。如果你自己手动处理分块解码、状态管理会麻烦很多。其次它带来了多模型支持的可能性。虽然当前项目只用了GPT-3.5 Turbo但AI SDK的接口设计是模型无关的。这意味着如果你未来想换成Anthropic的Claude、Google的Gemini甚至本地部署的Ollama模型只需要更换配置和调用函数业务逻辑代码改动可以降到最低。这种可移植性对于长期维护的项目至关重要。最后它内置了一些实用工具比如计算Token数量对于控制成本很有用、处理AI消息的历史记录等。这些工具函数能避免重复造轮子让开发者更专注于提示工程和业务逻辑。2.3 数据层与身份验证Supabase Clerk的组合拳为什么选择Supabase而不是独立的PostgreSQL数据库加自研API对于这样一个起步项目开发速度和一体化体验是关键。Supabase提供了开箱即用的实时数据库、身份认证、存储和边缘函数其与PostgreSQL的深度绑定意味着你可以用标准的SQL操作数据同时享受BaaS后端即服务的便利。在Chef Genie中Supabase很可能用于存储用户生成的菜谱历史、收藏夹或者用户自定义的食材偏好。通过Row Level SecurityRLS可以方便地实现数据隔离确保用户只能访问自己的数据。其JavaScript/TypeScript客户端库非常易用与Next.js的Server Components和Server Actions能很好地配合。身份验证则交给了Clerk。这是一个专门做开发者体验的Auth服务。它的优势在于提供了预构建的、可定制的UI组件如SignInButton /,UserButton /以及完整的用户管理后台。集成Clerk通常只需要几行代码就能获得邮箱/密码、社交登录Google, GitHub等、多因素认证等全套功能。对于个人开发者或小团队使用Clerk或类似服务如Auth.js远比从头实现一套安全、稳定的认证系统要高效、安全得多。这个组合Supabase Clerk实际上形成了一种“后端即服务”的架构让前端开发者能够快速构建出功能完整的全栈应用而无需深入后端基础设施的运维。2.4 UI与样式从Tailwind CSS到shadcn/ui的演进技术栈中UI部分的选择非常具有代表性Tailwind CSS Radix UI shadcn/ui。Tailwind CSS是实用优先的CSS框架它通过提供大量原子类来加速UI开发。在Chef Genie这样的项目中它能确保样式的高度定制化和一致性同时避免了传统CSS可能出现的类名冲突和样式臃肿问题。Radix UI是一个“无头”HeadlessUI组件库。它不提供任何样式只提供完全无障碍、功能完备的交互逻辑和组件状态管理。例如一个下拉菜单Dropdown的打开/关闭状态、焦点管理、键盘导航等复杂交互Radix UI都帮你处理好了。开发者需要自己用Tailwind CSS来给它“穿衣服”添加样式。这带来了极大的样式自由度和可控性。shadcn/ui正是基于上述两者理念的产物。它不是一个通过npm install安装的组件库而是一套你可以复制粘贴到自己项目中的高质量组件代码。这些组件使用Radix UI作为功能基座用Tailwind CSS编写样式。你可以完全控制这些组件的源代码并根据项目需求进行任意修改。这对于需要品牌定制化但又不想从零开始造轮子的项目来说是完美的选择。Chef Genie采用它既能获得美观、一致的UI又能保持技术的纯粹性和可维护性。3. 项目本地运行与核心配置详解3.1 环境准备与依赖安装要运行这个项目你需要一个相对现代的Node.js环境建议18.17或更高版本。项目使用pnpm作为包管理器这比传统的npm或yarn在安装速度和磁盘空间利用上更有优势。如果你没有安装pnpm可以通过npm install -g pnpm快速安装。第一步是克隆代码并安装依赖这看起来简单但有几个细节需要注意git clone https://github.com/giacomogaglione/chef-genie.git cd chef-genie pnpm install执行pnpm install时它会读取package.json和pnpm-lock.yaml确保安装的依赖版本与作者锁定的版本完全一致。这能最大程度避免“在我机器上是好的”这类问题。如果安装过程中出现网络问题可以尝试配置淘宝镜像源或使用科学的上网方式此处指代合规的网络加速服务需用户自行合法解决。3.2 环境变量配置项目的命脉这是最关键的一步所有第三方服务的接入都依赖于此。项目提供了一个.env.example文件作为模板。cp .env.example .env接下来你需要用文本编辑器打开新创建的.env文件并逐一填写以下关键变量OpenAI API Key (OPENAI_API_KEY)作用调用GPT模型生成菜谱的核心凭证。获取前往 OpenAI平台 注册登录创建新的API Key。注意新账号通常有免费额度但生成菜谱这类文本任务消耗token需关注用量和成本。安全警告此密钥绝不能提交到Git仓库。.env文件已被项目.gitignore排除请务必确认。Clerk密钥 (NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY,CLERK_SECRET_KEY)作用用于前端展示登录组件和后端验证用户身份。获取在 Clerk仪表板 创建新应用后在“API Keys”页面即可找到这两组密钥。NEXT_PUBLIC_前缀的变量意味着它可以在客户端代码中被访问而CLERK_SECRET_KEY仅用于服务端。Supabase连接信息 (NEXT_PUBLIC_SUPABASE_URL,NEXT_PUBLIC_SUPABASE_ANON_KEY,SUPABASE_SERVICE_ROLE_KEY)作用连接你的Supabase项目数据库。获取在 Supabase控制台 创建新项目后进入项目设置Settings - API页面。Project URL就是NEXT_PUBLIC_SUPABASE_URLanonpublic密钥就是NEXT_PUBLIC_SUPABASE_ANON_KEY。SUPABASE_SERVICE_ROLE_KEY是service_role密钥拥有绕过RLS的权限必须妥善保管仅用于服务端。配置延伸你还需要在Supabase中根据项目SQL文件如果提供创建数据表或者根据项目代码中的类型定义来设计表结构。通常你需要一个recipes表来存储生成的菜谱字段可能包括id,user_id关联Clerk用户ID,title,ingredients,instructions,created_at等。Vercel Analytics (VERCEL_ANALYTICS_ID)作用如果你将项目部署到Vercel并启用了Analytics功能可以在此配置ID以收集页面访问数据。本地开发时可留空或使用假值。实操心得建议在填写前先在对应的服务平台OpenAI, Clerk, Supabase完成账号注册和项目创建形成一个清晰的配置清单。一个常见的错误是复制密钥时多出空格或换行符导致连接失败。如果运行时出现认证错误第一件事就是检查.env文件中的值是否完全正确。3.3 启动开发服务器与初步验证配置完成后运行开发命令pnpm run dev如果一切顺利终端会输出类似“Ready on http://localhost:3000”的信息。此时在浏览器打开http://localhost:3000你应该能看到应用界面。首先测试的是身份验证流程。点击登录/注册按钮应该能跳转到Clerk提供的托管认证页面。成功注册或登录后会被重定向回应用并且UI上会显示你的用户头像或邮箱。这一步验证了Clerk集成是成功的。接下来测试核心的AI功能。在输入框中尝试输入一些食材比如“西红柿鸡蛋盐”选择“中式”口味点击生成。此时观察两个方面网络请求打开浏览器开发者工具的“网络”Network选项卡你应该能看到一个向/api或类似本地端点发出的请求并且响应类型可能是“text/event-stream”这表明流式响应在工作。界面反馈菜谱应该以逐字或逐段的形式显示出来而不是整个页面卡住后一次性弹出。如果这两步都成功了恭喜你项目的核心链路已经跑通。如果失败请根据终端和浏览器控制台的错误信息进行排查最常见的问题依然是环境变量配置错误或第三方服务如OpenAI的额度用尽。4. 核心功能实现与代码剖析4.1 AI菜谱生成提示工程与流式响应项目的核心灵魂在于如何与GPT对话让它扮演一个厨师。这不仅仅是一个简单的API调用而是涉及提示工程Prompt Engineering。在代码中你可能会找到一个类似这样的提示词模板const prompt 你是一位专业且富有创造力的厨师。请根据用户提供的食材、菜系偏好和饮食限制生成一份详细的菜谱。 请严格按照以下JSON格式回应不要包含任何其他解释 { title: 菜谱名称, description: 一段吸引人的简短描述, ingredients: [食材1及用量, 食材2及用量, ...], instructions: [步骤1, 步骤2, ...], tips: 一些烹饪小贴士 } 用户输入 食材${ingredients} 菜系偏好${cuisine} 饮食限制${restrictions} ;这个提示词做了几件关键事设定角色让AI进入“专业厨师”的语境。明确指令要求生成“详细的菜谱”。结构化输出强制要求以特定JSON格式回应这极大简化了后端处理逻辑。前端可以直接将流式响应的最终结果解析为JavaScript对象方便渲染。注入变量将用户输入的食材、口味等动态插入提示词中。在Server Action中调用Vercel AI SDK的流程大致如下import { streamText } from ai; import { openai } from ai-sdk/openai; export async function generateRecipe(ingredients: string, cuisine: string) { use server; // Next.js Server Action标记 const result streamText({ model: openai(gpt-3.5-turbo), // 指定模型 prompt: prompt, // 上面构建的提示词 temperature: 0.7, // 控制创造性0.7是一个平衡值 }); // 将AI SDK的流式响应转换为Next.js可用的流 return result.toDataStreamResponse(); }前端则使用useChatHook来连接这个Server Action并实时更新UIimport { useChat } from ai/react; export function RecipeForm() { const { messages, input, handleInputChange, handleSubmit, isLoading } useChat({ api: /api/recipe, // 指向你的Server Action路由 }); // messages数组会随着流式响应的推进自动更新 // 你可以遍历messages将最后一条AI回复的内容解析为JSON并渲染 }这种模式清晰地将AI逻辑隔离在服务端前端只负责展示和交互是构建AI应用的推荐架构。4.2 用户数据持久化与Supabase的交互生成菜谱后用户很可能希望保存它。这就涉及到将数据存入Supabase。通常在生成菜谱的Server Action中或生成完成后前端发起一个保存请求。首先你需要确保Supabase客户端在服务端和客户端都能正确初始化。项目通常会有一个lib/supabase.ts文件import { createClient } from supabase/supabase-js; const supabaseUrl process.env.NEXT_PUBLIC_SUPABASE_URL!; const supabaseAnonKey process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!; export const supabase createClient(supabaseUrl, supabaseAnonKey);在Server Action中保存菜谱时你需要使用服务端Supabase客户端并传入SUPABASE_SERVICE_ROLE_KEY以获得足够权限或者利用从Clerk获取的当前用户ID结合Supabase的RLS策略进行安全插入。假设有一个recipes表其RLS策略允许认证用户插入自己的数据CREATE POLICY Users can insert their own recipes ON recipes FOR INSERT TO authenticated WITH CHECK (auth.uid() user_id);那么在Server Action中保存逻辑可能如下import { supabaseServer } from /lib/supabase-server; // 使用服务端密钥初始化的客户端 import { auth } from clerk/nextjs/server; export async function saveRecipe(recipeData: any) { use server; const { userId } auth(); // 从Clerk获取当前用户ID if (!userId) throw new Error(未认证); const { error } await supabaseServer .from(recipes) .insert({ user_id: userId, title: recipeData.title, ingredients: recipeData.ingredients, instructions: recipeData.instructions, // ... 其他字段 }); if (error) throw error; return { success: true }; }前端则可以调用这个Server Action并处理成功或错误状态。这样一个完整的“生成-保存”闭环就实现了。4.3 前端状态管理与UI交互对于这样一个交互相对集中的应用状态管理并不复杂。React的useState、useEffect配合Server Actions和useChatHook基本够用。一个典型的页面状态可能包括inputIngredients: 用户输入的食材字符串。selectedCuisine: 选择的菜系。isGenerating: 是否正在生成菜谱来自useChat的isLoading。generatedRecipe: 解析后的菜谱对象。savedRecipes: 从Supabase获取的用户已保存菜谱列表。UI交互的重点在于良好的反馈。当用户点击“生成”时按钮应变为禁用状态并显示加载指示器如旋转图标。使用useChatHook提供的流式响应菜谱内容应逐行或逐段出现可以加入一个打字机效果Typewriter Effect的组件来提升体验。对于保存功能成功或失败应有即时的Toast通知。可以使用react-hot-toast或sonner与shadcn/ui风格很搭这样的轻量库来实现。5. 部署指南与生产环境考量5.1 部署到Vercel由于项目本身就是为Vercel优化的部署过程非常顺畅。推送代码到Git仓库将你的代码注意不要包含.env文件推送到GitHub、GitLab或Bitbucket。在Vercel导入项目登录 Vercel 点击“Add New” - “Project”选择你刚推送的仓库。配置环境变量在项目设置的“Environment Variables”页面将你在本地.env文件中配置的所有变量一一添加进去。这是最关键的一步确保生产环境能正确连接所有服务。部署Vercel会自动检测到这是Next.js项目并配置好构建命令和输出目录。点击“Deploy”即可。部署后Vercel会为你生成一个生产环境的URL如chef-genie.vercel.app。你可以访问这个链接测试生产环境下的认证、AI生成和数据库功能是否全部正常。5.2 生产环境优化与安全加固将开发项目变为可用的生产应用还需要一些额外步骤自定义域名与SSL在Vercel项目设置中可以绑定你自己的域名并自动配置免费的SSL证书。Clerk生产实例在Clerk仪表板中将你的应用环境从“开发”切换到“生产”。你需要为生产环境配置允许的回调URL即你的Vercel生产域名。生产环境下的密钥与开发环境不同记得在Vercel环境变量中更新。Supabase生产数据库Supabase的免费计划足够支撑小规模使用。确保生产环境连接的是Supabase生产项目的URL和密钥。考虑为生产数据库建立单独的连接并与开发数据隔离。OpenAI API成本与限额在OpenAI平台为生产环境的API Key设置使用限额Spending Limits防止意外超支。同时考虑对用户进行限流Rate Limiting例如每个用户每小时只能生成有限次数的菜谱这可以在Next.js的Server Action中通过检查数据库记录来实现。错误监控与日志集成像Sentry或Logtail这样的服务监控运行时错误和性能。Vercel自身也提供函数日志和Analytics。内容安全策略CSP由于涉及AI生成内容建议配置严格的CSP头防止XSS攻击。Next.js可以通过next.config.js中的headers函数进行配置。5.3 性能与扩展性思考当前架构对于中小流量已经足够。如果用户量增长可以考虑以下方向AI响应缓存相同的食材和偏好组合可能会生成相同或相似的菜谱。可以在Server Action中引入缓存层如使用Vercel KV、Upstash Redis或直接在Supabase中缓存结果对请求参数进行哈希短时间内相同的请求直接返回缓存结果大幅降低OpenAI API调用成本和响应时间。数据库索引优化如果recipes表数据量变大频繁按user_id或created_at查询务必在相应字段上创建数据库索引。静态资源优化未来如果添加菜谱图片应使用Next.js的Image /组件进行自动优化并考虑将图片存储到Supabase Storage或Vercel Blob中。6. 常见问题排查与调试技巧在实际运行和魔改过程中你肯定会遇到各种问题。这里记录一些典型问题的排查思路。6.1 环境变量相关错误症状应用启动失败或功能登录、AI生成不可用控制台报错“Missing API Key”或“Invalid Supabase URL”。排查本地确认.env文件在项目根目录且变量名与代码中process.env.XXX引用的完全一致注意大小写。重启开发服务器pnpm dev。Vercel生产环境登录Vercel控制台进入项目设置 - Environment Variables逐一核对所有变量是否已添加且值正确。特别注意密钥中是否有意外空格。修改后需要触发重新部署。6.2 AI生成失败或响应慢症状点击生成后无反应或等待很久后报错。排查OpenAI额度首先检查OpenAI平台账户的额度是否用尽或过期。网络问题Server Action调用OpenAI API受服务器网络影响。如果部署在Vercel其服务器全球分布通常网络良好。本地开发时不稳定的网络可能导致超时。提示词与参数检查传递给AI的提示词是否过长或格式错误。过高的temperature参数可能导致生成时间变长。尝试将temperature调低至0.5或设置max_tokens限制生成长度。流式响应中断检查前端useChat配置和后端Server Action的流式返回逻辑。确保没有在流结束前过早关闭连接。6.3 身份验证问题症状无法登录/注册或登录后用户状态不持久。排查Clerk密钥确认NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY和CLERK_SECRET_KEY配对正确且来自同一Clerk应用实例。回调URL在Clerk仪表板的“Redirects”设置中确保添加了你的应用地址本地开发是http://localhost:3000生产环境是你的Vercel域名到“Allowed redirect URLs”和“Allowed callback URLs”。中间件配置Next.js项目通常有一个middleware.ts文件来处理Clerk认证。检查其matcher配置确保需要保护的页面路由被正确覆盖。6.4 数据库操作失败症状保存菜谱失败前端报“RLS policy violation”或“insert error”。排查RLS策略登录Supabase控制台进入“Authentication” - “Policies”检查recipes表的INSERT策略是否已正确创建并启用。确保策略中的auth.uid()能与Clerk的用户ID对应上。有时需要创建一个自定义函数来将Clerk的userId映射到Supabase的auth.users表。用户ID映射这是一个常见痛点。Clerk的用户ID与Supabase内置的auth.users表的ID不同。常见的做法是在用户首次登录时在一个自定义的profiles表或直接在你的recipes表中将Clerk的userId存储为一个字段如clerk_user_id。然后你的RLS策略需要基于这个自定义字段进行校验而不是auth.uid()。或者使用Clerk的Webhooks在用户注册时在Supabase的auth.users表中创建一条对应记录但这更复杂。表结构确认你插入的数据字段名、类型与数据库表定义完全一致。6.5 样式或组件显示异常症状页面布局错乱或shadcn/ui组件无法交互。排查Tailwind CSS类名冲突检查是否在全局CSS或组件中引入了其他可能冲突的样式库。Radix UI Provider缺失许多Radix UI组件需要被对应的Provider包裹如ToastProvider,DialogProvider。检查应用的根布局app/layout.tsx是否包含了必要的Provider。CSS变量未定义shadcn/ui的样式依赖于一套CSS变量如--background,--foreground。检查app/globals.css中是否引入了主题CSS文件并正确定义了这些变量。调试时养成习惯首先查看浏览器开发者控制台的“Console”和“Network”选项卡这里通常有最直接的错误信息。对于服务端错误查看Vercel部署日志或本地终端输出。对于数据库问题Supabase控制台的“SQL Editor”和“Table Editor”是验证数据和SQL语句的好帮手。
