convex-quickstart 是 Convex 模板库中的入门模板,目标是根据一句话想法,本地运行一个最小化的 Convex + Next.js Web 模板,并使用匿名开发部署。它强调精简:只启动本地开发服务器,不包含发布步骤,也不预置身份认证。\n\n主要能力与使用方式\n\n该模板通过 quickstart 工作流(recipe quickstart-recipe@^2,参数为 {idea, template})创建项目、安装依赖、启动匿名后端与 Web 开发服务器;当输出开发 URL 后,将其提供给用户打开。若要在模板之外构建更多功能,需先展示简短方案并等待确认。工作流成功后不应重复运行。convex/ 下的代码应交给 convex-expert 能力处理,且不应引入 Postgres、Redis、Express,而应使用 Convex 原语;也不应添加托管/发布或预置认证,除非用户明确要求。\n\n降级规则\n\n若脚手架无法运行(非交互会话、无网络、沙箱临时目录,或用户只需要代码而非应用),则跳过该工作流,直接编写标准 Convex 项目。所有后端代码必须放在 convex/ 下(如 schema.ts、函数),不能放在项目根目录;Convex 函数只能从 convex/ 目录运行。除非明确要求,不编写脚手架或文档文件(如 START_HERE.md、ARCHITECTURE.md、MANIFEST.txt、README 等)。\n\n数据访问与导入约束\n\n在编写任何 convex/*.ts 前:对于可能增长的表,不要使用无界的 .collect(),应使用 .withIndex(...) 配合 .paginate(...) 或 .take(n);对应 SQL WHERE 的场景应使用索引而非 .filter();.withIndex(...) 回调仅支持 eq/gt/gte/lt/lte,没有 .range(...) 方法。导入方面:query/mutation/action/internalQuery/internalMutation/internalAction 来自 ./_generated/server;api/internal 来自 ./_generated/api;应用代码中不得从 convex/server 导入。固定字符串/枚举成员使用 v.literal("exact value"),而非裸字符串。"use node" 只能出现在仅含 action 的模块顶部,不得出现在同时导出 query 或 mutation 的文件中。缺少 "use node" 的文件(包括 http.ts 路由处理器)不得导入 Node 内置模块(crypto/fs/path/http/child_process/os,无论是否带 node: 前缀);尽可能使用 Web Crypto(crypto.subtle)代替导入 crypto。\n\n保留名称与 HTTP 路由\n\n不得导出 const <jsReservedWord> = ...(如 delete、new、class、function、return)作为 query/mutation/action 的导出名,否则 esbuild 解析失败。表名或索引名不得以 _ 开头(如 migrations), 为保留前缀,推送时会报 TableNameReserved/IndexNameReserved。httpRouter 不支持 Express 风格的 :param 路径段(path: "/users/:id" 只会匹配该字面字符串,成为死代码);应使用 pathPrefix 并自行解析末尾段。每个 http.route({...}) 处理器必须用 ./_generated/server 中的 httpAction(...) 包装;裸 async (ctx, request) => {...} 能通过类型检查但不是有效的 HTTP action。ctx.runQuery/ctx.runMutation/ctx.runAction 需要代码生成的函数引用(api.foo.bar/internal.foo.bar),不能使用原始导入的模块成员(如 import * as queries from "./queries"; ctx.runQuery(queries.getX, ...)),后者能编译但运行时会失败。\n\n自检规则\n\n在宣布后端工作完成前,需验证其可编译并可推送:运行 npx tsc --noEmit 并推送到部署。优先使用项目现有部署;否则在 npx convex whoami 成功时运行 npx convex dev --once,仅在失败时使用 CONVEX_AGENT_MODE=anonymous npx convex dev --once。对已登录用户强制匿名会重新绑定 .env.local,使其失去预期的持久可发布云部署。完成前修复所有报告的错误。\n\n适用场景与限制\n\n适用于快速起步的 Convex + Web 原型和本地开发。限制包括:默认不包含发布和认证;需遵循上述代码规范;无法运行脚手架的环境需降级为直接编写代码。收费、价格、平台支持与完整使用步骤暂未提供。
convex-quickstart
编程与开发
更新于 11-11 17:59