自定义域名管理

v3.0.0+

tcb domains 命令自 v3.0.0 起提供，替代原 tcb service domain 的自定义域名功能。

tcb domains 用于管理 HTTP 访问服务的自定义域名。绑定自定义域名后，您可以通过自己的域名访问云开发 HTTP 服务，并通过路由规则将流量转发到云函数、云托管、静态托管等上游服务。

cors vs domains 的区别

• tcb cors：管理 Web SDK 安全域名白名单（CORS 鉴权），控制哪些网页域名可以访问云开发资源。详见 安全域名管理。
• tcb domains：管理 HTTP 访问服务的自定义域名，需绑定 SSL 证书，与 tcb routes 路由规则联动。

前置条件

绑定自定义域名前，请确保：

1. 域名已完成 ICP 备案
2. 已在腾讯云 SSL 证书控制台 申请并上传有效的 SSL 证书，获取证书 ID
3. 绑定成功后，需将域名的 DNS 解析 CNAME 记录指向云开发环境域名

查看自定义域名列表

查看当前环境已绑定的自定义域名：

tcb domains ls -e <envId>

支持分页和过滤：

# 分页查询
tcb domains ls -e <envId> --limit 50 --offset 0

# 按域名过滤
tcb domains ls -e <envId> --filter "Domain=api.example.com"

# 按接入方式过滤
tcb domains ls -e <envId> --filter "AccessType=CDN"

# 多条件组合（且关系，&连接）
tcb domains ls -e <envId> --filter "DomainType=HTTPSERVICE&AccessType=DIRECT"

--filter 可过滤字段：

字段	说明	可选值
Domain	域名	任意域名字符串
DomainType	域名类型	HTTPSERVICE（默认）、CBR、ANYSERVICE、AI_AGENT、VM、INTEGRATION_CALLBACK
AccessType	接入方式	DIRECT、CDN、CUSTOM

提示

默认只展示用户手动绑定的 HTTPSERVICE 类型域名。如需查看其他类型域名，使用 --filter "DomainType=CBR" 等。

绑定自定义域名

将自定义域名绑定到 HTTP 访问服务：

# 基本用法（直连接入，默认）
tcb domains add api.example.com --certid <certId> -e <envId>

# CDN 接入
tcb domains add api.example.com --certid <certId> --access-type CDN -e <envId>

# 自定义接入（需指定 CNAME 源站）
tcb domains add api.example.com --certid <certId> --access-type CUSTOM --custom-cname origin.example.com -e <envId>

# 绑定后禁用（默认启用）
tcb domains add api.example.com --certid <certId> --disable -e <envId>

命令参数：

参数	说明	必填
<domain>	要绑定的域名	是
--certid <certId>	SSL 证书 ID，在腾讯云 SSL 证书控制台获取	是
--access-type <type>	接入方式：DIRECT（直连，默认）、CDN（接入云开发 CDN）、CUSTOM（自定义）	否
--custom-cname <cname>	自定义 CNAME，仅当 --access-type CUSTOM 时可用	否
--disable	绑定后禁用域名（默认启用）	否

注意

• 同一域名不能重复绑定
• 绑定成功后，需配置 DNS CNAME 解析才能正常访问

解绑自定义域名

解绑已绑定的自定义域名：

tcb domains rm api.example.com -e <envId>

注意

如果域名下仍有路由绑定，解绑操作会失败。需先使用 tcb routes delete 删除该域名下的所有路由，再执行解绑操作。

# 查看域名下的路由
tcb routes list -e <envId> --filter "Domain=api.example.com"

# 删除路由后再解绑域名
tcb routes delete api.example.com -e <envId> -p /api/*
tcb domains rm api.example.com -e <envId>

典型使用流程

# 1. 绑定自定义域名（需先有 SSL 证书）
tcb domains add api.example.com --certid abc123 -e <envId>

# 2. 为域名添加路由规则（将流量转发到云托管服务）
tcb routes add -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/*","upstreamResourceType":"CBR","upstreamResourceName":"my-service"}]}'

# 3. 配置 DNS：将 api.example.com 的 CNAME 解析指向云开发环境域名

# 4. 验证访问
curl https://api.example.com/

命令速查

命令	说明
tcb domains ls	查看自定义域名列表
tcb domains add <domain> --certid <certId>	绑定自定义域名
tcb domains rm <domain>	解绑自定义域名