Convex 静态主机
直接在 Convex 上托管静态React/Vite 应用程序的 Convex 组件: 否
单独的托管供应商,没有DNS来电,没有第二个部署目标. 运行一个
命令,您的前端为 https://<deployment>.convex.site
与你的后端.
特征
- 🚀 部署一个命令 : 构建、 推后端并上传静态文件 单步.
- 🔄 SPA 路线 : 没有扩展的路径返回到
index.html。 。 。 . - ⚡ 智能缓存 : 静态文件为速度缓存, 安全更新当 部署了一个新的版本.
- 🔔 最新部署通知: 显示连接的用户当 a 新版本已经准备好.
- 🔒 认证上传 : 上传通过 Convex CLI 已认证会话; 没有公开上传端点 .
- 🧹 自动清理 : 先前0.2.x部署的文件为垃圾 每次部署都收集到 移民指南涵盖一次性v1清理.
快速启动
升级现有的0.1.x应用程序? 这不是只更新软件包 。 点 您的编码代理 0.1.x至0.2.x 移徙指南 在它改变任何事情之前。 指南涵盖了破旧的再装入, 保存认证和 Webhook URL, 历史 v1 blob 审计, 部署 排序和核查.
npm install @convex-dev/static-hosting
npx @convex-dev/static-hosting setup
对于新设置,命令将组件添加到 convex/convex.config.ts 财务报告和审定财务报表
创建一个 deploy 脚本在 package.json。它不覆盖已有的
曲线配置或 deploy 剧本. 完成任何手工编辑
命令,并确认 npm run deploy 运行前引用此软件包 :
npm run deploy
你的应用程序是现场直播 https://<deployment>.convex.site。 。 。 .
设置
1. 安装
npm install @convex-dev/static-hosting
2. 登记构成部分
convex/convex.config.ts数字 :
import { defineApp } from "convex/server";
import staticHosting from "@convex-dev/static-hosting/convex.config";
// Your own HTTP endpoints (convex/http.ts) are served under /api so the
// static site can own the root.
const app = defineApp({ httpPrefix: "/api" });
app.use(staticHosting, { httpPrefix: "/" });
export default app;
这是最快的服务模式。 组件拥有 /,而你的应用程序
convex/http.ts 移动路线 /api/...。 。 。 .
如果已有的回调或认证路径必须停留在根上, 请使用 应用自主根路由。作为东道主 在子路径下,见 在子路径下上山。 。 。 .
3. 添加部署脚本
{
"scripts": {
"deploy": "npx @convex-dev/static-hosting deploy"
}
}
就是这样.
将已有的 HTTP 路径保留在根上
不要仅仅为了添加静态托管而移动稳定的webhook, auth, 或 API URL. 离开 组件的 HTTP 路径已卸载, 并记录您的静态齐全 已存在的路由器.
convex/convex.config.ts数字 :
import { defineApp } from "convex/server";
import staticHosting from "@convex-dev/static-hosting/convex.config";
const app = defineApp();
app.use(staticHosting); // no httpPrefix
export default app;
convex/http.ts数字 :
import { httpRouter } from "convex/server";
import { registerStaticRoutes } from "@convex-dev/static-hosting";
import { components } from "./_generated/api";
const http = httpRouter();
// Register exact app routes first. Existing auth/webhook helpers can stay here.
// auth.addHttpRoutes(http);
registerStaticRoutes(http, components.staticHosting);
export default http;
精准的路由战胜了静态的call-all-,因此已存在的URL继续工作. 这个 组件仍然拥有上传、部署状态和文件存储。 此模式添加 内部查询和存储在未标记的请求中获取,所以倾向于 当您不需要 root- level app 路由时, 组件自有模式.
使用非 Vite 捆绑器
这个 deploy 步骤和 upload --build 设定 VITE_CONVEX_URL组合器
使用不同的环境变量常规,将您的构建脚本包成
通过值 :
对于博览会:
{
"scripts": {
"build": "EXPO_PUBLIC_CONVEX_URL=${VITE_CONVEX_URL:-$EXPO_PUBLIC_CONVEX_URL} npx expo export --platform web"
}
}
下一个.js:
{
"scripts": {
"build": "NEXT_PUBLIC_CONVEX_URL=${VITE_CONVEX_URL:-$NEXT_PUBLIC_CONVEX_URL} next build"
}
}
模式 ${VITE_CONVEX_URL:-$VAR} 用途 VITE_CONVEX_URL 如果 CLI 设置
否则就回到你的组合变量 这保持了两个
CLI驱动的建设和独立 npm run build 工作时.
部署
使用单一命令部署 Convex 后端和静态文件 :
npx convex login # first time only
npx @convex-dev/static-hosting deploy
这个 deploy 命令 :
- 与制作建立前端
VITE_CONVEX_URL。 。 。 . - 部署Convex后端.
- 上传
dist/到康维克斯.
为了获得更多的控制,可以分别运行两个半个:
npx convex deploy
npx @convex-dev/static-hosting upload --build --prod
你的应用程序是现场直播 https://<deployment>.convex.site。 。 。 .
发展工作流程
开发期间使用您的普通前端 Dev 服务器 :
# Terminal 1
npx convex dev
# Terminal 2
npm run dev
对于Vite,这保持了HMR和快速的本地反馈. 静态托管是部署 目标,不是替换dev服务器。 上传每次编辑到开发 部署速度较慢,并丢失了HMR,即使代理写入了大部分代码. 人类仍需要快速循环的视觉检查 瞬间UI状态 调试中.
在发布前,对开发部署进行一次烟雾测试:
npx @convex-dev/static-hosting upload --build
然后使用 deploy 用于生产。 这个分块保持了 dev 循环的快度, 但仍然
在运输前测试真正的HTTP,缓存,基道和SPA行为.
CLI 选项
npx @convex-dev/static-hosting deploy [options]
-d, --dist <path> Path to dist directory (default: ./dist)
-c, --component <name> Component instance name (default: staticHosting)
--skip-build Skip the build step (use existing dist)
--skip-convex Skip Convex backend deployment
--build-command <cmd> Build command to run (default: 'npm run build')
--no-spa Disable SPA fallback (404 instead of /index.html)
--spa Enable SPA fallback (default)
--cdn Use the legacy convex-fs integration
--cdn-delete-function Legacy app function that deletes CDN blobs
npx @convex-dev/static-hosting upload [options]
-d, --dist <path> Path to dist directory (default: ./dist)
-c, --component <name> Component instance name (default: staticHosting)
--prod Deploy to production deployment
-b, --build Run 'npm run build' with VITE_CONVEX_URL set
--build-command <cmd> Override the build command; implies --build
--no-spa Disable SPA fallback (404 instead of /index.html)
--spa Enable SPA fallback (default)
--cdn Use the legacy convex-fs integration
--cdn-delete-function Legacy app function that deletes CDN blobs
-j, --concurrency <n> Parallel upload workers (default: 5)
每次上传都是在解剖学上公布的,所以访问者从没有看到提到过的页面 尚未提供的资产。 上传失败离开上一个部署 现场直播 旧文件被安全清理 见 一体化.md 用于上传限制和生命周期细节.
Convex HTTP 路由目前支持GET,但不是HEAD. 配置时间检查 轻量级请求而不是头部请求.
如果将组件以不同名称挂载,则
app.use(staticHosting, { name: "custom" }),通过 --component custom 财务报告和审定财务报表
替换每个生成 components.staticHosting 参考文献
components.custom。 。 。 .
不使用 --cdn 为了新的融合。 它瞄准一个更古老的 ConvexFS HTTP API
并仅用于现有部署。 遗留的 CDN 用户必须保留
应用自有根路由因 /fs/upload 财务报告和审定财务报表 /fs/blobs/* 是根应用程序
路线。 见 INTEGRATION.md 用于当前限制.
警卫
上传 API 使用 内部职能 在组件中只能是 通过:
npx convex run(需要 Convex CLI 认证)- 构成部分中的其他对流功能(仅服务器侧)
这意味着未经授权的用户 无法 上传文件到您的网站, 即使它们 了解您的 Convex URL .
部署后重新装入提示( 可选)
如果你想要一个能促使用户在新部署舰艇时重新装入的横幅,
在您的应用程序中显示部署查询并跳入 <UpdateBanner />数字 :
convex/staticHosting.ts数字 :
import { exposeDeploymentQuery } from "@convex-dev/static-hosting";
import { components } from "./_generated/api";
export const { getCurrentDeployment } = exposeDeploymentQuery(
components.staticHosting,
);
src/App.tsx数字 :
import { UpdateBanner } from "@convex-dev/static-hosting/react";
function App() {
return (
<>
<UpdateBanner message="New version!" buttonText="Reload" />
{/* ... */}
</>
);
}
UpdateBanner 决定 api.staticHosting.getCurrentDeployment 自动.
如果您在不同的模块名下再导出查询,请明确通过:
import { api } from "../convex/_generated/api";
<UpdateBanner getCurrentDeployment={api.myModule.getCurrentDeployment} />;
对于自定义 UI,请使用钩:
import { useDeploymentUpdates } from "@convex-dev/static-hosting/react";
const { updateAvailable, reload, dismiss } = useDeploymentUpdates();
在子路径下上山
如果根部有其它路线,则将静态站点挂入子路径:
app.use(staticHosting, { httpPrefix: "/app/" });
您还需要告诉你的捆绑者关于基础路径, 所以释放的 HTML
引用正确的 URL。 CLI设定 STATIC_HOSTING_BASE_PATH 环境 var
匹配组件运行时的挂载, 所以 vite.config.ts 能够
直接读取:
import { defineConfig } from "vite";
export default defineConfig({
base: process.env.STATIC_HOSTING_BASE_PATH ?? "/",
});
根挂载的应用程序不需要这个; 默认是 /。用于网页包装
publicPath,用于下一个.js assetPrefix。 。 。 .
SPA 路线
默认情况下,请求一个没有文件扩展名的路径与
上传文件返回到 index.html,所以客户端路线喜欢
/dashboard/settings 重新装入的工作。 对于未知路径的多页应用程序
应该是一个真正的404,部署与 --no-spa数字 :
npx @convex-dev/static-hosting deploy --no-spa
装置是随部署而储存的,所以它用你运送的密码行走
而不是生活在单独的地道里 请求带有扩展名的路径
(例如:. /missing.js总是在找不到时404, 不论设置如何 .
从0.1.x升级
0.2.0 将上传和文件存储移入组件. 你必须移除
exposeUploadApi 从 convex/staticHosting.ts 财务报告和审定财务报表 调用您的
资产 因为0.1.x文件存在于应用程序的存储中. 抓住两个
当前 v1 显示和更广泛的应用存储目录 : 上传时间较长 v1
可能留下了静态块,当前清单不再列出.
然后可以选择两种服务模式:
- 如果静态网站可以拥有
/,将组件挂起,去掉旧的registerStaticRoutes电话. - 如果已有的 HTTP 路由必须停留在
/,保留convex/http.ts联 合 国registerStaticRoutes电话 0.2执行部分读取了新的 组件自有文件,而不改变这些路由 URL.
见奉献 0.1.x至0.2.x 移徙指南 准确 步骤、核查、回滚和可选的分阶段切入.
如何运作
- 构建 : 您的捆绑器释放
dist/。 。 。 . - 上传 : cLI 使用您认证的 Convex 会话生成签名 上传 URL,将文件推向 Convex 存储,记录元数据,以及 GC 旧 部署.
- 服务: hTTP 动作查看请求的路径, 将文件流到
右边
Content-Type,对散装资产适用长期缓存,以及 倒计时index.html用于SPA路线.
示例
见 example/ 用于一个完整的Vite + React app.
npm install
npm run dev
捐款
见 捐款额。 。 。 .
许可证
阿帕奇 - 2.0