Vibe Stack：用架构规则约束AI编程，解决Next.js与Supabase开发中的安全与兼容性问题

1. 项目概述用架构规则为AI编程上“紧箍咒”如果你和我一样已经深度依赖像 Cursor、GitHub Copilot 或 Claude 这样的 AI 编程助手来加速开发那你一定也经历过那种“冰火两重天”的体验。一方面生产力确实得到了前所未有的提升一些重复性的样板代码、简单的 CRUD 逻辑AI 助手几乎可以信手拈来。但另一方面你肯定也踩过不少坑AI 生成的代码看起来完美无瑕编译也顺利通过但一上线就暴露出各种安全问题、兼容性错误或者引入了已经被弃用的依赖。最让人头疼的是这些问题往往不是语法错误而是更深层次的“架构幻觉”——AI 基于它海量的训练数据给你推荐了一个看似合理、实则过时或不安全的模式。这就是 Vibe Stack 诞生的背景。它不是一个普通的 Next.js 15 Supabase 脚手架而是一套“架构规则优先”的解决方案。其核心在于它预置了 29 条.mdc格式的架构规则这些规则能直接作用于你的 AI 编程助手如 Cursor从物理层面约束 AI 的代码生成行为让它从一开始就“被迫”写出符合最佳实践的、安全的、面向生产的代码。简单来说它把我们从“事后救火员”的角色中解放出来让我们能真正信任 AI 生成的代码并专注于业务逻辑的创新。2. 核心问题拆解AI 编程的“幻觉”到底有多危险在深入 Vibe Stack 的解决方案之前我们必须先理解它要解决的“敌人”是什么。AI 编程助手的“幻觉”并非指它胡言乱语而是指它基于过时、不安全或与当前项目架构不符的训练数据生成出“逻辑自洽但实际错误”的代码。这些错误极具隐蔽性常规的语法检查工具如 ESLint、TypeScript往往无法捕获。2.1 典型“幻觉”场景与真实风险让我们看几个在 Next.js 和 Supabase 生态中极其常见且危害巨大的 AI 幻觉案例身份验证安全漏洞getSession()vsgetUser()幻觉代码AI 经常在服务器组件或 API Route 中推荐使用getSession()来获取用户会话。现实风险在 Supabase 的 SSR服务端渲染最佳实践中getSession()已被明确标记为不安全因为它可能返回未经验证的会话对象。正确的做法是使用getUser()它会验证 JWT 令牌的有效性。如果 AI 生成了getSession()你的应用可能在未登录状态下错误地认为用户已认证导致数据泄露。Vibe Stack 的规则supabase-auth-security.mdc规则会直接禁止 AI 生成getSession()强制其使用getUser()。Next.js 15 兼容性陷阱同步访问params幻觉代码AI 可能会在generateStaticParams或页面组件中同步地、直接地访问params对象。现实风险Next.js 15 的一个重大变更就是params和searchParams变成了异步的 Promise。同步访问会导致运行时崩溃。这是版本升级中最容易踩的坑之一。Vibe Stack 的规则nextjs15-params.mdc规则会强制 AI 以异步方式await params处理这些参数彻底避免崩溃。依赖过时与模式错误幻觉代码导入已被弃用的supabase/auth-helpers-nextjs包。现实风险这个包已被 Supabase 官方弃用转而推荐使用supabase/ssr进行服务端集成。使用旧包不仅可能失去新特性支持还可能存在未知的安全隐患。Vibe Stack 的规则supabase-ssr-only.mdc规则会阻止导入废弃的包并引导 AI 使用正确的supabase/ssr。数据库安全缺失忽略行级安全策略幻觉代码AI 生成创建数据库表的 SQL 语句但没有附带任何 Row Level Security 策略。现实风险Supabase 的默认策略是拒绝所有访问。如果没有正确配置 RLS你的数据表要么完全无法访问要么更糟糕完全暴露。AI 不会自动为你考虑数据隔离。Vibe Stack 的规则supabase-rls.mdc规则会在 AI 生成CREATE TABLE语句时强制其同时生成启用 RLS 和基础策略的模板确保“安全默认”。我的实操心得这些“幻觉”最可怕的地方在于它们通常不会在本地开发或构建阶段暴露。你可能愉快地开发了好几周直到应用上线第一个真实用户触发某个边缘条件时系统才崩溃或泄露数据。此时排查成本极高。Vibe Stack 的思路是“治未病”在代码生成的源头设立关卡。2.2 为什么传统 Linter 解决不了这个问题ESLint 和 TypeScript 是静态代码分析工具它们检查的是代码的“形式”语法是否正确、类型是否匹配、是否有未使用的变量。而 AI 的“架构幻觉”是代码的“语义”问题这段代码在当前的框架版本、当前的依赖库、当前的安全上下文中是否是正确的、最优的实现方式例如getSession()在语法上完全正确类型也匹配静态分析工具无从挑剔。只有深刻理解 Supabase 身份验证演进史和当前安全建议的“架构规则”才能判断出它是错误的。这就是.mdc规则的价值——它们将领域专家的架构知识编码成了机器可读、AI 可执行的约束。3. Vibe Stack 架构规则深度解析Vibe Stack 的核心资产就是那 29 条.mdc规则。.mdc是 Cursor 编辑器所使用的一种规则文件格式它允许你以声明式的方式定义代码风格、架构模式和禁止模式。当你在 Cursor 中打开一个配备了.mdc规则的项目时这些规则会直接影响 Cursor 内置的 AI 模型如 Claude 3.5 Sonnet的代码补全和建议。3.1 规则的工作原理与分类这些规则并非简单的“关键词过滤”而是基于模式匹配和上下文的智能约束。它们大致可以分为以下几类安全与合规类这是规则的基石。security.mdc集成了 OWASP Top 10 的防护思路例如它会强制在 API 路由中实现速率限制模式防止 AI 生成没有防护的端点。env-management.mdc严格区分服务器端和客户端环境变量。它会阻止 AI 将包含敏感信息的变量以NEXT_PUBLIC_前缀暴露并强制对服务端密钥进行正确的分类和访问。框架最佳实践类确保代码符合特定框架的最新范式。server-vs-client-components.mdc智能判断组件应放在服务端还是客户端。它会阻止 AI 在仅使用服务端特性的组件上添加不必要的‘use client’指令从而优化 bundle 大小和渲染性能。hydration-safety.mdc预防 React 服务端渲染中常见的“水合不匹配”错误。例如它会阻止 AI 在组件中直接使用localStorage或Date.now()这类在服务端和客户端可能产生不同值的代码。数据流与状态管理类规范数据如何流动。api-validation.mdc为 Next.js Route Handlers 和 Server Actions 提供输入验证模式。它会引导 AI 在处理请求参数时优先使用 Zod 进行模式验证和类型转换而不是直接信任req.body。caching-revalidation.mdc教导 AI 正确使用 Next.js 的缓存和重新验证机制。例如在生成数据更新操作后会自动补全revalidatePath或revalidateTag调用保证 UI 状态的同步。外部服务集成类标准化第三方服务的接入方式。stripe-payments.mdc确保所有 Stripe 相关的逻辑如创建 Checkout Session、验证 Webhook 签名都在服务端执行并包含必要的错误处理和事件类型安全。file-uploads.mdc为 Supabase Storage 的上传操作提供安全模板包括文件类型校验、大小限制和服务器端路径处理。3.2 免费版与付费版规则对比项目提供了 5 条核心免费规则这足以解决前文提到的最致命问题。付费版本则是一个完整的“生产就绪”知识体系。规则类别免费版 (5条)付费完整版 (29条)解决的问题深度身份验证supabase-auth-security.mdc同上并整合入更全面的security.mdc从“防止致命错误”到“实现全方位防护”框架兼容nextjs15-params.mdc同上并扩展至performance.mdc(并行获取等)从“避免崩溃”到“性能优化”依赖管理supabase-ssr-only.mdc同上并包含typescript-strict.mdc(禁用any)从“用对包”到“写出严谨的类型代码”组件设计server-vs-client-components.mdc同上并增加hydration-safety.mdc从“正确划分边界”到“避免渲染错误”数据安全supabase-rls.mdc同上并深化为database-design.mdc(包含UUID、索引等)从“开启RLS”到“设计健壮的数据模式”其他领域无支付、缓存、API验证、环境变量、文件上传、测试等20条规则覆盖一个生产级SaaS应用的所有关键层面我的实操心得免费版的 5 条规则就像汽车的“安全带和气囊”是保命的底线。而付费版的 29 条规则则是包含了“车道保持、自动刹车、盲点监测”的完整智能驾驶系统。如果你是在启动一个严肃的商业项目投资完整版相当于为项目聘请了一位不知疲倦的、精通现代全栈最佳实践的架构师长期来看其节省的调试时间和避免的生产事故价值远超其价格。4. 从零开始使用 Vibe Stack 构建你的第一个受保护功能让我们抛开概念实际动手操作一遍看看在 Vibe Stack 的规则“护航”下用 AI 助手开发一个功能是多么的顺畅和安全。我们将实现一个常见的需求在受保护的仪表板页面从数据库中获取并展示当前用户的待办事项列表。4.1 环境准备与项目初始化首先按照 Quick Start 的步骤克隆并运行项目# 1. 克隆项目 git clone https://github.com/vibestackdev/vibe-stack.git my-ai-safe-app cd my-ai-safe-app # 2. 安装依赖 npm install # 这里使用 npm如果你习惯用 pnpm 或 yarn需要先删除 package-lock.json # 3. 配置环境变量 cp .env.example .env.local接下来你需要一个 Supabase 项目。前往 supabase.com 创建一个新项目。在项目设置 - API 页面找到Project URL和anon public密钥将它们填入.env.local文件# .env.local NEXT_PUBLIC_SUPABASE_URL你的Supabase项目URL NEXT_PUBLIC_SUPABASE_ANON_KEY你的anon公钥 SUPABASE_SERVICE_ROLE_KEY你的service_role密钥仅服务端用务必保密启动开发服务器npm run dev现在用Cursor 编辑器打开my-ai-safe-app文件夹。这是关键一步只有 Cursor 能主动读取并应用项目根目录下的.mdc规则文件。4.2 在 AI 规则约束下创建数据库表假设我们还没有todos表。在 Cursor 中打开一个与数据库相关的文件比如lib/supabase/server.ts旁边或者直接新建一个sql/todos.sql文件。然后我们尝试用 AI 来生成建表语句。你的操作在 Cursor 的聊天框里输入“帮我创建一个 Supabase 数据库表用来存储用户的待办事项字段包括 id、user_id、title、is_complete 和 created_at。”在没有 Vibe Stack 规则的项目中AI 可能会生成CREATE TABLE todos ( id BIGSERIAL PRIMARY KEY, user_id UUID REFERENCES auth.users(id), title TEXT NOT NULL, is_complete BOOLEAN DEFAULT FALSE, created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() );这个代码看起来没问题但缺少了最关键的 Row Level Security (RLS)。表创建后默认是禁止所有访问的你的应用会无法读写数据。在 Vibe Stack 项目中由于supabase-rls.mdc规则生效AI 生成的代码会是这样的CREATE TABLE todos ( -- 使用UUID而非BIGSERIAL更适合分布式系统 id UUID DEFAULT gen_random_uuid() PRIMARY KEY, user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE, title TEXT NOT NULL, is_complete BOOLEAN DEFAULT FALSE, created_at TIMESTAMPTZ DEFAULT NOW() ); -- 立即启用行级安全策略 ALTER TABLE todos ENABLE ROW LEVEL SECURITY; -- 策略用户只能操作自己的待办事项 CREATE POLICY Users can manage their own todos ON todos FOR ALL USING (auth.uid() user_id) WITH CHECK (auth.uid() user_id);看到了吗AI 不仅创建了表还自动将主键改为了更通用的UUID。添加了ON DELETE CASCADE确保用户删除时其待办事项也被清理。自动补全了ENABLE ROW LEVEL SECURITY语句。生成了一条基础的 RLS 策略确保数据隔离。这就是架构规则的力量——它让 AI 的输出从“语法正确”跃升到了“生产就绪”。4.3 实现受保护的服务器组件页面现在我们需要在app/dashboard/page.tsx或新建的app/dashboard/todos/page.tsx中展示这些待办事项。你的操作在对应的页面文件里直接开始用自然语言编写注释或向 Cursor AI 提问“获取当前用户的待办事项列表并展示。”在没有规则的项目中AI 可能生成有风险的代码// ❌ 危险示例使用了已弃用的 auth-helpers 且用了 getSession import { createServerComponentClient } from ‘supabase/auth-helpers-nextjs‘; import { cookies } from ‘next/headers‘; export default async function TodosPage() { const supabase createServerComponentClient({ cookies }); const { data: session } await supabase.auth.getSession(); // 不安全的调用 const { data: todos } await supabase .from(‘todos‘) .select(‘*‘) .eq(‘user_id‘, session?.user?.id); // 可能为 undefined return div{/* 渲染 todos */}/div; }在 Vibe Stack 项目中多个规则会同时作用引导 AI 生成正确代码supabase-ssr-only.mdc规则阻止导入supabase/auth-helpers-nextjs。supabase-auth-security.mdc规则禁止使用getSession()。server-vs-client-components.mdc规则判断此组件无需客户端交互不会添加‘use client‘。最终AI 生成的代码会是这样的// ✅ 安全示例使用正确的包和方法 import { createServerClient } from ‘supabase/ssr‘; import { cookies } from ‘next/headers‘; import { redirect } from ‘next/navigation‘; export default async function TodosPage() { const cookieStore await cookies(); // 使用 createServerClient 创建服务端客户端 const supabase createServerClient( process.env.NEXT_PUBLIC_SUPABASE_URL!, process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!, { cookies: { getAll: () cookieStore.getAll() } } ); // 使用 getUser() 安全地获取已验证的用户信息 const { data: { user } } await supabase.auth.getUser(); // 如果未认证重定向到登录页 if (!user) { redirect(‘/login‘); } // 安全地查询当前用户的数据 const { data: todos, error } await supabase .from(‘todos‘) .select(‘*‘) .eq(‘user_id‘, user.id) // user.id 保证存在 .order(‘created_at‘, { ascending: false }); if (error) { console.error(‘Error fetching todos:‘, error); // 在实际项目中这里应该有更优雅的错误处理UI } return ( div className“p-8“ h1 className“text-2xl font-bold mb-4“Your Todos/h1 ul className“space-y-2“ {todos?.map((todo) ( li key{todo.id} className“flex items-center gap-2 p-2 border rounded“ input type“checkbox“ checked{todo.is_complete} readOnly / span className{todo.is_complete ? ‘line-through text-gray-500‘ : ‘‘} {todo.title} /span /li ))} /ul /div ); }这段代码是立即可用的它包含了正确的 Supabase SSR 客户端初始化。安全的用户认证检查 (getUser())。自动的重定向逻辑。类型安全的数据库查询。基本的错误处理和 UI。你不需要记忆这些模式AI 在规则的约束下已经为你生成了最佳实践。你的角色从“代码纠错员”变成了“产品定义者”。5. 进阶配置MCP 集成与“Vibe Coding”工作流Vibe Stack 的付费版本提到了MCPModel Context Protocol集成和“Vibe Coding”理念。这是将 AI 辅助开发提升到新层次的关键。5.1 MCP 服务器赋予 AI 感知和操作能力MCP 是 Anthropic 提出的一种协议它允许 AI 模型安全地访问外部工具和数据源比如文件系统、数据库、GitHub 等。Vibe Stack 付费版预配置了 4 个 MCP 服务器文件系统 MCPAI 可以读取项目结构、文件内容甚至在你确认后创建、修改文件。这让你可以用自然语言说“在lib/utils下创建一个日期格式化函数”AI 就能直接完成。GitHub MCPAI 能读取仓库的 Issue、Pull Request甚至创建分支和提交。你可以说“基于最新的 main 分支创建一个feat/user-settings的分支”AI 会通过 MCP 调用 Git 命令。Supabase MCPAI 能直接查询你的数据库 schema、运行简单的 SQL 来验证数据或者理解表之间的关系。这在开发数据密集型功能时极其有用。浏览器 MCPAI 可以控制一个无头浏览器进行页面截图、测试用户流程或抓取公开数据在合规前提下。配置示例以文件系统 MCP 为例在 Cursor 设置中你需要编辑 Cursor 的 MCP 配置文件通常在~/.cursor/mcp.json添加类似以下的配置具体参数需参考 Vibe Stack 提供的详细指南{ “mcpServers”: { “filesystem”: { “command”: “npx“, “args”: [“-y“, “modelcontextprotocol/server-filesystem“, “/path/to/your/project“], “env”: {} } } }配置成功后你在 Cursor 中就可以直接要求 AI“看看我们app/api目录下有哪些路由文件然后为/api/users设计一个 GET 和 POST 处理函数。” AI 会先通过 MCP 读取目录再基于架构规则生成符合规范的代码。5.2 “Vibe Coding”三阶段循环这是 Vibe Stack 倡导的一种与 AI 协作的心智模型和工作流文档中称之为“代理循环”阶段一意图规划你不要直接说“写一个登录按钮”。而是向 AI 描述最终目标和上下文。例如“作为一个用户我想在导航栏右侧看到一个登录按钮点击后弹出我们设计系统中的模态框进行认证。当前的项目使用shadcn/ui的对话框组件并且我们已经有了app/(auth)/login页面。”效果AI 会理解整体意图而不是机械地生成一个孤立的按钮它可能会建议复用现有路由或组件。阶段二约束性生成AI 根据你的意图结合项目中的.mdc规则、TypeScript 类型、现有组件库生成一份代码草案。由于规则的存在这份草案在架构上基本是安全的。阶段三验证与迭代你或通过配置的 CI/CD运行类型检查、测试和 Lint。如果规则有遗漏或出现新问题你可以将错误反馈给 AI“这个组件在服务端使用了window对象导致 hydration 错误请修正。” AI 会学习这次修正并在未来避免同类问题。你还可以将这种新发现的“幻觉模式”贡献给 Vibe Stack 社区形成新的规则。这个循环将开发者从繁琐的细节中解放出来专注于高层设计和业务逻辑同时通过规则保证底层代码的质量。6. 常见问题与实战排坑指南即使有了强大的规则护航在实际开发中仍可能遇到一些困惑或边缘情况。以下是我在实践过程中总结的一些常见问题和解决方法。6.1 规则不生效或 AI 仍然生成错误代码可能原因及解决方案问题现象可能原因解决方案Cursor 完全没有应用规则提示1. 未在 Cursor 中打开包含.mdc文件的项目根目录。2. Cursor 版本过旧。1. 使用File-Open Folder打开整个项目文件夹而不是单个文件。2. 更新 Cursor 到最新版本。部分规则生效部分不生效.mdc文件存在语法错误或路径问题。检查项目根目录下的.cursor/rules文件夹如果存在或直接位于根目录的.mdc文件。确保文件格式正确。可以尝试重启 Cursor。AI 绕过了规则生成了被禁止的模式AI 模型特别是非 Cursor 内置的模型的“越狱”或规则定义不够严格。1. 在 Cursor 设置中确保优先使用其内置的“Claude 3.5 Sonnet”模型它对.mdc规则支持最好。2. 审查并强化相关.mdc规则。规则可以组合使用例如同时禁止某个函数并推荐替代函数。6.2 如何为自定义需求添加新的架构规则Vibe Stack 的规则是开源的免费部分和可扩展的。当你发现 AI 在你的特定技术栈比如使用了某个特定的 UI 库或 ORM中反复出现同一种错误模式时你可以自己编写.mdc规则。一个简单的自定义规则示例禁止使用any类型假设你的项目要求极其严格的 TypeScript你可以在项目根目录创建一个no-any-types.mdc文件# 这是一个简化的示例实际 .mdc 语法请参考 Cursor 官方文档 name: “Strict TypeScript - No Any“ description: “禁止在代码中使用 any 类型强制使用明确类型或 unknown。“ rules: - pattern: “:any“ description: “使用了 any 类型” suggestion: “请使用更具体的类型或使用 unknown 并进行类型守卫。” severity: “error“编写规则的心得从问题出发先精确描述 AI 生成的错误代码模式。提供正确方案在suggestion中清晰地给出替代代码或模式。测试规则在本地创建一个测试文件尝试让 AI 生成违规代码看规则是否能正确拦截和提示。贡献社区如果你觉得这个规则具有通用性可以向 Vibe Stack 仓库提交 Pull Request帮助更多人。6.3 与现有项目或团队工作流的整合场景一已有大型 Next.js 项目你不需要重写整个项目。只需将 Vibe Stack 的.mdc规则文件复制到你现有项目的根目录然后在 Cursor 中打开该项目。规则会立即开始作用于新编写的代码。你可以从最重要的安全规则如supabase-auth-security.mdc开始逐步引入其他规则。这相当于为你的老项目引入了“架构巡检员”。场景二团队协作确保团队所有使用 Cursor 的成员都在同一份.mdc规则文件下工作。最好的方式是将这些.mdc文件纳入版本控制如 Git。这样团队的代码风格和架构标准就能通过 AI 助手实现自动对齐大幅减少 Code Review 中关于基础模式和安全的争论。6.4 性能与心智负担有人可能会担心这么多规则会不会限制 AI 的创造力或拖慢开发速度从我数月的使用经验来看恰恰相反。初期适应在刚开始的一两个小时你可能会觉得需要不断“纠正”AI 的提议因为它在尝试你熟悉的旧模式。但很快AI 就学习并适应了你的规则约束。中期高效一旦适应AI 生成的代码第一次可用的概率极高。你不再需要反复检查getUser用对了没、RLS 加了没、参数是不是异步。这节省了大量的调试和重构时间。长期收益项目代码库的质量和一致性得到了底层保障。新成员加入时只要使用配置好的 Cursor 环境就能写出符合团队标准的代码极大降低了培训成本和维护成本。Vibe Stack 及其背后的架构规则理念代表了一种新的 AI 辅助编程范式从“人适应 AI 的随机输出”到“AI 适应人的架构规范”。它通过将资深开发者的架构经验编码成机器可执行的规则让 AI 这个强大的“实习生”从一开始就走在正确的道路上。无论是其免费的 5 条核心安全规则还是付费的完整生产就绪系统都为希望在 Next.js 和 Supabase 生态中稳健、高效开发的团队提供了一个极具价值的解决方案。我的体会是它最大的价值不在于省下了写几行代码的时间而在于避免了那些在未来可能耗费数天甚至数周去排查的、由 AI “幻觉”引发的深层 Bug。在 AI 编程时代这或许是最值得的一笔投资。