convex-deploy

介绍 Convex 后端和全栈应用的部署生命周期、环境及安全发布策略。 - 模型：每个项目有一个生产部署，每位团队成员有一个开发部署，每个分支有一个预览部署。 - 预览部署处于 beta 阶段，并会自动清理；数据播种需要使用 `--preview-run`。 - 本地部署：`npx convex dev --local --once`，没有公共 URL，Node action 需要 Node 18。 - Agent Mode：开发期间，AI 编码 Agent 使用 `CONVEX_AGENT_MODE=anonymous`，以限制权限。 - 环境变量按部署分别设置；系统变量为 `CONVEX_CLOUD_URL` 和 `CONVEX_SITE_URL`。 - 安全变更规则：架构必须与数据匹配；使用可选字段、回填或联合迁移；保持函数向后兼容；已计划任务的参数必须保持有效。 - 项目配置：`convex.json` 可以更改函数路径和 Node 运行时；静态代码生成处于 beta 阶段。 - 暂停部署会导致新的调用返回错误、已计划任务排队、cron 任务跳过；你应该先在开发环境中测试。

部署操作

• 核心命令：npx convex dev、npx convex deploy、npx convex codegen、npx convex run（生产环境使用 --prod）。
• Agent Mode：作为 AI Agent 进行迭代时，你应该使用 CONVEX_AGENT_MODE=anonymous npx convex dev --once，以安全地生成代码生成产物。
• 部署目标解析：CONVEX_DEPLOY_KEY 优先；否则使用 CONVEX_DEPLOYMENT 项目的生产部署。
• 构建步骤：npx convex deploy --cmd "npm run build"；需要时使用 --cmd-url-env-var-name。
• 部署密钥：production、preview、dev、admin（你不得提交或记录这些密钥）。
• 托管流程：
  • Vercel/Netlify 构建命令应该使用 npx convex deploy --cmd 'npm run build'。
  • 你必须为每个环境（Preview 与 Production）设置 CONVEX_DEPLOY_KEY。
  • 通过 --preview-run 'functionName' 为预览环境播种数据。
  • 自定义托管：部署后端，并在其他地方托管前端；自定义域名需要覆盖 CONVEX_CLOUD_URL 并重新部署；CONVEX_SITE_URL 可选。

必需输出

• 你必须使用文档中的准确 CLI 命令和标志。
• 你必须说明部署目标解析方式（部署密钥或 CONVEX_DEPLOYMENT）。
• 你必须指出部署产生的副作用：架构验证、索引回填、代码生成、打包。
• 在适用时，你应该始终提及 .convex.site 与 .convex.cloud URL 的用途。

部署模型

• 每个项目有一个生产部署，每位团队成员有一个云端开发部署。
• 预览部署按分支创建，并会在一段时间后自动清理。
• 本地部署仅用于开发，并作为 npx convex dev 的子进程运行。

CLI 工作流

开发

• npx convex dev：
  • 监视文件，并将更改推送到开发部署。
  • 重新生成 convex/_generated/*。
  • 你应该使用 --tail-logs 控制日志输出。
• 本地开发：
  • 使用 npx convex dev --local --once 启动本地后端。
  • 注意：没有公共 URL；HTTP 请求需要代理（例如 ngrok）。
  • 本地 Node action 需要 Node 18。

部署

• npx convex deploy：
  • 对函数进行类型检查。
  • 重新生成代码。
  • 对函数、架构和索引进行打包并推送。
• 部署目标解析：
  • 如果设置了 CONVEX_DEPLOY_KEY，则部署到该密钥指定的目标。
  • 否则使用 CONVEX_DEPLOYMENT 所属项目的生产部署。
• 可选构建命令：
  • npx convex deploy --cmd "npm run build"
  • 使用 --cmd-url-env-var-name 自定义环境变量名称。

部署密钥

• Production 部署密钥：指向项目的生产部署（通常用于 CI）。
• Preview 部署密钥：为每个分支创建预览部署。
• Dev 部署密钥：限定到单个开发部署。
• Admin 密钥：完全控制权限；用于匿名本地部署。
• 安全性：你不得将部署密钥粘贴到代码中或提交到版本历史中。

预览部署

• Beta 功能，生命周期管理会自动清理（默认 5 天）。
• 预览部署名称与分支绑定；重新部署会替换之前的预览部署。
• 填充数据需要在部署期间运行函数（--preview-run）。

环境变量

• 必须通过控制面板或 npx convex env 为每次部署设置。
• 同一个键可能需要在 dev 和 prod 中设置不同的值。
• 系统变量：
  • 用于客户端 RPC 的 CONVEX_CLOUD_URL。
  • 用于 HTTP actions 的 CONVEX_SITE_URL。
• 运行时不得基于 process.env 分支导出；函数在部署时设置。

安全发布规则

• Schema 必须与现有数据匹配；验证失败时会阻止部署。
• 安全的 Schema 变更：
  • 添加表。
  • 添加可选字段，回填数据，然后将其设为必填。
  • 使用 v.union 扩大范围，回填数据，然后缩小范围。
• 旧客户端仍在运行期间，函数必须保持向后兼容。
• 已调度的函数必须接受之前已调度的参数。

索引回填

• 新索引会在部署期间回填；这可能会拖慢生产环境的推送。
• 对于大型表，应使用分阶段索引（包括搜索／向量索引）。
• 移除索引会在部署时将其删除；必须确保没有代码路径依赖这些索引。

URL

• HTTP actions：https://<deployment>.convex.site。
• 客户端 URL：https://<deployment>.convex.cloud（通过 CONVEX_CLOUD_URL）。
• 应提醒用户不要混用 .convex.site 和 .convex.cloud。

响应检查清单

• 说明环境（dev/prod/preview/local）。
• 提供准确的命令和必需的环境变量。
• 列出安全注意事项（Schema、函数、已调度任务）。
• 排查问题时说明日志位置（CLI 或控制面板）。