convex-quickstart

快速入门：运行精简版 Convex 模板

根据创意在本地搭建一个精简版 Next.js + Convex 模板，并使用匿名开发部署。设计力求精简：本地开发服务器，无需发布步骤，也不预置身份验证。

工作流

1. 使用 {idea, template} 运行配方 quickstart-recipe@^2（该包会获取并缓存模板；固定版本的离线备用方案）。它会创建项目、安装依赖、启动后端（匿名）和 Web 开发服务器。
2. 它打印出开发 URL 后，为用户打开该 URL。
3. 简要说明计划，并在开发模板之外的功能前请求确认。

规则

• 如果配方已报告成功，切勿再次运行。
• 将 convex/ 下的所有代码交由 convex-expert 能力处理。
• 不要添加 Postgres/Redis/Express——使用 Convex 原语。
• 不要在此处添加托管/发布或预置身份验证——除非用户提出要求，否则保持模板精简。
• 降级规则——如果脚手架无法运行（非交互式会话、没有网络、使用沙盒临时目录，或用户只想要代码而不是应用），则跳过配方，直接编写标准 Convex 项目。所有后端代码都放在 convex/ 下（schema.ts、函数）——绝不要放在项目根目录；Convex 函数只能从 convex/ 目录运行。除非用户明确要求，否则不要编写任何脚手架/文档文件（例如 START_HERE.md、ARCHITECTURE.md、MANIFEST.txt、冗长的 README）。“为我构建一个后端”意味着写代码，而不是搞形式。
• 数据访问与导入——在编写任何 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" 的文件中绝不要导入 Node 内置模块（crypto/fs/path/http/child_process/os，无论是否带 node: 前缀）——包括 http.ts 路由处理程序；尽可能使用 Web Crypto（crypto.subtle）代替导入 crypto。
• 保留名称——绝不要将 export const <jsReservedWord> = ...（例如 delete、new、class、function、return）用作 query/mutation/action 导出名称；esbuild 无法解析。表名或索引名绝不能以下划线 _ 开头（例如 _migrations: defineTable(...)）——_ 是保留字符，推送时会报 TableNameReserved/IndexNameReserved 错误。
• HTTP 路由——httpRouter 不支持 Express 风格的 :param 片段（path: "/users/:id" 只会匹配该字面字符串，属于无效代码）；应使用 pathPrefix 并自行解析末尾片段。每个 http.route({...}) 的 handler: 都必须用 ./_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, ...) 虽然能编译，但会在运行时失败）。
• 自我验证规则——在宣布后端工作完成之前，验证代码能否编译并推送：运行 npx tsc --noEmit，并将其推送到一个部署中。优先使用项目已有的部署；否则，如果 npx convex whoami 成功，则运行 npx convex dev --once；只有在该命令失败时，才运行 CONVEX_AGENT_MODE=anonymous npx convex dev --once。对已登录的用户强制使用匿名模式会重新绑定 .env.local，使他们失去预期的持久、可发布云部署。完成前修复报告的所有错误——一次验证就能发现错误的相对导入、重复符号、括号不匹配等问题，避免它们导致部署失败。