自定义域名接入(/domains)
用途:把用户已经拥有的域名指向其 Convex 应用。整个过程不购买域名,也不需要注册商凭据,只需向用户提供其自行创建的精确记录。
主要能力与使用方式:
-
确定目标:已发布的站点主机(用于静态托管),或该部署的 HTTP actions URL(可通过 npx convex env get CONVEX_SITE_URL 或仪表盘获取)。
-
给出精确 DNS 记录:告知用户在其注册商处创建 CNAME(根域使用 A/ALIAS)以及 TXT 验证记录,需提供具体的主机名和值字符串,而非占位符。
-
附加自定义域名:在 Convex 中操作(仪表盘 → 部署 → Custom Domains,或使用 CLI),然后等待验证。DNS 传播可能需要数分钟到数小时,应告知用户,不要无限轮询。
-
处理认证来源:如果应用使用认证(passkeys/OAuth),需将认证来源(SITE_URL / RP_ID / ORIGIN 环境变量)重新绑定到新域名并重新部署,否则新域名上登录会失效。
-
验证:确认域名通过 HTTPS 正常提供应用,包括已配置的根域到 www 重定向。
限制与规则:
- 绝不索要注册商凭据,记录由用户自行创建。
- 必须包含 TXT 验证记录,不能只给 CNAME。
- 重新绑定域名会改变认证来源,必须随后重新部署,否则登录会失效。
适用场景:已拥有域名、希望将其接入 Convex 应用,并需要在接入后保持认证正常工作的开发者。