convex-domains

使用自选服务商设置自定义域名

引导用户通过自己的域名注册商，将域名指向 Convex 应用：确定目标地址（托管或部署 URL）、创建 DNS 记录、绑定自定义域名；如果应用使用身份验证，还要重新绑定身份验证源。

工作流

1. 确定目标地址：已发布网站的主机名（适用于 *.convex.app 静态托管），或部署的 HTTP actions URL。
2. 检查用户的服务商是否有已完成身份验证的 DNS CLI，并主动提出自动创建记录：Cloudflare → flarectl dns create（注意：wrangler 本身不管理 DNS 记录），或通过其令牌环境变量调用 CF API；Route53 → aws route53 change-resource-record-sets；Google Cloud DNS → gcloud dns record-sets create；DigitalOcean → doctl compute domain records create；Vercel DNS → vercel dns add。先以只读方式检查身份验证状态（flarectl user info / aws sts get-caller-identity / doctl account get）；展示准确命令，并在运行前征得同意。
3. 如果没有已完成身份验证的 CLI（或用户拒绝），明确告知用户要在其域名注册商处创建哪些记录：CNAME（或根域上的 A/ALIAS）以及 TXT 验证记录，并提供具体的主机名和值，不要使用占位符。
4. 将域名添加为 Convex 自定义域名（通过控制台或 CLI），并等待验证完成；说明 DNS 传播可能需要几分钟到几小时。使用 dig +short 验证记录是否生效。
5. 如果应用使用身份验证（通行密钥/OAuth），将身份验证源（SITE_URL / RP_ID / ORIGIN 环境变量）重新绑定到新域名，然后重新部署/发布。
6. 验证：域名通过 HTTPS 提供应用服务；如果已配置根域 → www 重定向，也要验证该重定向。

规则

• 绝不索取或处理域名注册商凭据。用户机器上已经完成身份验证的 CLI 可以使用——凭据保留在工具中；切勿为此安装 CLI 或运行其登录/身份验证流程，也绝不回显令牌。
• 对正在使用的域名所做的 DNS 更改会影响用户可见内容：运行前展示准确命令并征得确认；运行后使用 dig 验证。
• 始终包含 TXT 验证记录，不能只提供 CNAME。
• 重新绑定域名会更改身份验证源——之后必须重新发布，否则登录会失效。