自定义域名管理
v3.0.0+
tcb domains 命令自 v3.0.0 起提供，替代原 tcb service domain 的自定义域名功能。
tcb domains 用于管理 HTTP 网关的自定义域名。绑定自定义域名后，您可以通过自己的域名访问云开发资源，并通过路由规则将流量转发到云函数、云托管、静态托管等上游服务。
平台版支持
domains ls / add / edit / rm 四个命令支持平台版：通过 --platform-id <platformId> 指定平台版资源池 ID 即在平台版资源池下操作域名，与 -e <envId> 互斥，未指定时保持环境级行为不变。缓存刷新命令（cache purge / cache task）不支持平台版。平台版是账号维度的套餐方案，详见平台版概述。
cors vs domains 的区别
tcb cors：管理 Web SDK 安全域名白名单（CORS 鉴权），控制哪些网页域名可以访问云开发资源。详见 安全域名管理。tcb domains：管理 HTTP 网关的自定义域名，需绑定 SSL 证书，与tcb routes路由规则联动。
前置条件
绑定自定义域名前，请确保：
- 域名已完成 ICP 备案
- 已在腾讯云 SSL 证书控制台 申请并上传有效的 SSL 证书，获取证书 ID
- 绑定成功后，需将域名的 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"
# 查询平台版资源池下的域名（v3.8.3+）
tcb domains ls --platform-id <platformId>
--filter 可过滤字段：
| 字段 | 说明 | 可选值 |
|---|---|---|
Domain | 域名 | 任意域名字符串 |
DomainType | 域名类型 | HTTPSERVICE（默认）、CBR、ANYSERVICE、AI_AGENT、VM、INTEGRATION_CALLBACK |
AccessType | 接入方式 | DIRECT、CDN、CUSTOM、EO |
提示
默认只展示用户手动绑定的 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>
# 在平台版资源池下绑定域名（v3.8.3+）
tcb domains add api.example.com --certid <certId> --platform-id <platformId>
命令参数：
| 参数 | 说明 | 必填 |
|---|---|---|
<domain> | 要绑定的域名 | 是 |
--certid <certId> | SSL 证书 ID，在腾讯云 SSL 证书控制台获取 | 是 |
--access-type <type> | 接入方式：DIRECT（直连，默认）、CDN（接入云开发 CDN）、CUSTOM（自定义）、EO（接入云开发 EdgeOne） | 否 |
--custom-cname <cname> | 自定义 CNAME，仅当 --access-type CUSTOM 时可用 | 否 |
--disable | 绑定后禁用域名（默认启用） | 否 |
--platform-id <platformId> | 平台版资源池 ID。指定后在平台版资源池下绑定域名，与 -e 互斥（v3.8.3+） | 否 |
注意
- 同一域名不能重复绑定
- 绑定成功后，需配置 DNS CNAME 解析才能正常访问
更新自定义域名配置
v3.8.3+
更新已绑定自定义域名的域名级字段（证书、接入方式、启用状态等），不修改路由配置。仅更新显式传入的字段：
# 更新 SSL 证书
tcb domains edit api.example.com --certid <certId> -e <envId>
# 变更接入方式为 CDN
tcb domains edit api.example.com --access-type CDN -e <envId>
# 自定义接入（需指定 CNAME 源站）
tcb domains edit api.example.com --access-type CUSTOM --custom-cname origin.example.com -e <envId>
# 禁用域名
tcb domains edit api.example.com --disable -e <envId>
# 预览将要更新的配置（不实际执行）
tcb domains edit api.example.com --certid <certId> --dry-run -e <envId>
# 更新平台版资源池下的域名（v3.8.3+）
tcb domains edit api.example.com --platform-id <platformId> --access-type EO --certid <certId> --enable
命令参数：
| 参数 | 说明 | 必填 |
|---|---|---|
<domain> | 要更新的域名 | 是 |
--certid <certId> | 要更新的 SSL 证书 ID，在腾讯云 SSL 证书控制台获取 | 否 |
--access-type <type> | 要更新的接入方式：DIRECT（直连）、CDN（接入云开发 CDN）、CUSTOM（自定义）、EO（接入云开发 EdgeOne） | 否 |
--custom-cname <cname> | 要更新的自定义 CNAME，仅当 --access-type CUSTOM 时可用 | 否 |
--enable | 将域名更新为启用状态，与 --disable 互斥 | 否 |
--disable | 将域名更新为禁用状态，与 --enable 互斥 | 否 |
--dry-run | 预览模式，仅展示将要更新的配置，不实际执行 | 否 |
--platform-id <platformId> | 平台版资源池 ID。指定后在平台版资源池下更新域 名，与 -e 互斥（v3.8.3+） | 否 |
注意
- 至少指定一个要更新的字段（
--certid/--access-type/--custom-cname/--enable/--disable） - 域名需已绑定（
tcb domains ls可查看），如需新增域名请使用tcb domains add - 仅更新域名级配置，路由规则的修改请使用
tcb routes edit
解绑自定义域名
解绑已绑定的自定义域名：
tcb domains rm api.example.com -e <envId>
# 解绑平台版资源池下的域名（v3.8.3+）
tcb domains rm api.example.com --platform-id <platformId>
注意
如果域名下仍有路由绑定，解绑操作会失败。需先使用 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>
刷新缓存
刷新 HTTP 访问服务域名的 CDN 或 EdgeOne（EO）缓存。域名需已接入 CDN 或 EdgeOne 才能刷新。
刷新粒度说明
url（精确 URL）：CDN、EO 均支持，目标需包含http://或https://协议前缀prefix（目录）：仅 EO 支持，目标需包含协议前缀，例如https://example.com/static/host（整个域名）：仅 EO 支持，目标可为裸域名或带协议的域名
提交刷新任务
# 刷新单个 URL（CDN 或 EO）
tcb domains cache purge https://example.com/index.html -d example.com -e <envId>
# 批量刷新多个 URL
tcb domains cache purge https://example.com/a.js https://example.com/b.css -d example.com -e <envId>
# 目录刷新（仅 EO）
tcb domains cache purge https://example.com/static/ -d example.com -e <envId> -t prefix
# 域名刷新（仅 EO）
tcb domains cache purge https://example.com -d example.com -e <envId> -t host
# 显式指定缓存类型并等待完成
tcb domains cache purge https://example.com/index.html -d example.com -e <envId> -c eo --wait
命令参数：
| 参数 | 说明 | 必填 |
|---|---|---|
<targets...> | 刷新目标列表，单次最多 20 个，单条最长 2048 字符 | 是 |
-d, --domain <domain> | HTTP 访问服务域名 | 是 |
-t, --type <type> | 刷新粒度：url（默认）/ prefix（目录）/ host（域名）。目标以 / 结尾时自动识别为 prefix | 否 |
-c, --cache-type <cacheType> | 缓存类型：cdn / eo。默认根据域名接入方式自动识别，一般无需填写 | 否 |
-w, --wait | 提交后等待刷新完成再返回（适合 CI/CD 场景） | 否 |
注意
- 域名需接入 CDN 或 EdgeOne（EO）后才能刷新缓存
- CDN 域名仅支持 URL 粒度刷新，目录（prefix）与域名（host）刷新为 EO 独有能力
- URL / 目录目标需包含
http://或https://协议前缀
查询刷新任务
# 查询单个任务进度
tcb domains cache task <taskId> -d example.com -e <envId>
# 列出域名近 7 天的刷新历史
tcb domains cache task -d example.com -e <envId>
# 按刷新粒度过滤
tcb domains cache task -d example.com -e <envId> -t prefix
命令参数：
| 参数 | 说明 | 必填 |
|---|---|---|
[taskId] | 任务 ID，由刷新任务返回；传入时查询单个任务进度，不传则列出历史记录 | 否 |
-d, --domain <domain> | HTTP 访问服务域名 | 是 |
-t, --type <type> | 按刷新粒度过滤：url / prefix / host | 否 |
-c, --cache-type <cacheType> | 缓存类型：cdn / eo | 否 |
--limit <limit> | 分页大小，默认 20，最大 1000 | 否 |
--offset <offset> | 分页偏移量，默认 0 | 否 |
典型使用流程
# 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 edit <domain> | 更新自定义域名配置 |
tcb domains rm <domain> | 解绑自定义域名 |
tcb domains cache purge <targets...> -d <domain> | 提交缓存刷新任务 |
tcb domains cache task [taskId] -d <domain> | 查询缓存刷新任务 |
domains ls/add/edit/rm支持通过--platform-id <platformId>操作平台版资源池（v3.8.3+）。