用途:把 Convex 静态自托管集成到现有项目中,并保持跨项目可重复。使用前必须先做上游更新检查,优先运行 bash skills/convex-self-hosting/scripts/check-upstream.sh,并阅读上游 INTEGRATION.md、README 手动设置章节及 Convex 文档索引;用 npm view @convex-dev/self-hosting version 确认包发布状态。若上游文档与本地规则冲突,以上游为准并说明变化。
实施前需先确认:以 get-convex/self-hosting 为唯一事实来源;目标应用是 Vite、Next.js、Expo web 导出还是其他打包器;使用根路径还是 /app 之类前缀;采用一次性部署还是后端与静态分开部署;包未发布时选择 GitHub 依赖、本地 vendored 副本还是等待 npm 发布。
安装:包已发布时用 npm install @convex-dev/self-hosting;未发布时用 npm install github:get-convex/self-hosting#main,如需确定性构建应固定 commit SHA。
主要文件改动:convex/convex.config.ts 中 app.use(selfHosting);convex/staticHosting.ts 暴露上传 API 与部署查询;convex/http.ts 注册静态路由,可选 pathPrefix 与 spaFallback;package.json 增加 deploy 与 deploy:static 脚本。
部署:首次执行 npm install、npx @convex-dev/self-hosting setup、npx convex dev --once、npm run deploy;后续用 npm run deploy,或分两步 npx convex deploy 与 npx @convex-dev/self-hosting upload --build --prod。使用 upload 部署时不要先运行 npm run build。
限制与注意:上传 API 必须保持内部,不得暴露为公开 HTTP action;Vite 默认用 --build 流程,Next.js 与 Expo 需按上游文档传递 VITE_CONVEX_URL;已有 API 路由建议用 pathPrefix: "/app"。完成前需给出上游文档时间戳、所选包路径及原因、改动文件清单和后续命令。