gateway
cloudbaserc.json 的 gateway 字段用于 tcb deploy 声明式部署网关，定义如何把 HTTP 请求按「域名 + 路径」转发到云函数、静态托管等上游服务。
| 属性 | 值 |
|---|---|
| 类型 | Object |
| 说明 | 网关路由配置，用于 tcb deploy 声明式部署网关 |
子字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
routes | Array<Object> | 是 | 网关路由列表 |
routes[]
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
path | String | 是 | — | URL 路径，如 /api。必须以 / 开头，不支持通配符，每段仅允许字母、数字、.、_、-，每段不超过 50 字符；不可使用保留前缀 /__auth、/.well-known |
target | String | 是 | — | 目标资源：function:<name>（云函数）或 hosting:<name>（静态托管）。云函数自动区分类型：HTTP 型创建为 WEB_SCF 路由、Event 型创建为 SCF 路由；hosting 只支持一级路径（如 / 或 /web），多级路径报错 |
domain | String | 否 | 环境默认域名 | 绑定的自定义域名。未绑定时 tcb deploy 自动绑定（幂等），无需先执行 tcb domains add |
certId | String | 否 | — | SSL 证书 ID。显式配置优先；未配置且域名未绑定时按域名匹配已签发证书（仅 Status=1 未过期），匹配不到则部署报错 |
accessType | String | 否 | DIRECT | 接入方式：DIRECT / CDN（即将下线）/ CUSTOM（需配 customCname）/ EO |
customCname | String | 否 | — | accessType=CUSTOM 时必填的 CNAME 记录 |
protocol | String | 否 | HTTP_AND_HTTPS | 域名协议：HTTP / HTTPS / HTTP_AND_HTTPS / HTTP_TO_HTTPS / HTTPS_TO_HTTP |
enable | Boolean | 否 | true | 域名启用状态，作用于域名绑定，取该域名分组第一条路由的配置；路由本身始终启用 |
pathRewrite | Object | 否 | — | 路径重写：{ "prefix": "/newpath" } 或 { "staticStorePrefix": "/xxx" }。两者只能填一个；hosting 路由未配置时自动生成 prefix=对应 hosting 的部署路径 |
enablePathTransmission | Boolean | 否 | false | 路径透传：true 传完整路径给上游，false 只传匹配后的路径。hosting 路由未显式配置 pathRewrite 时开启会与自动生成的重写冲突报错 |
enableAuth | Boolean | 否 | false | 是否开启身份认证 |
qpsPolicy | Object | 否 | — | QPS 限频：{ "qpsTotal": 100-100000, "qpsPerClient": { "limitBy": "ClientIP" | "UserID", "limitValue": 0-30 } }，limitBy 与 limitValue 均必填 |
示例
{
"gateway": {
"routes": [
{ "path": "/api", "target": "function:api-server" },
{ "path": "/web", "target": "hosting:web", "accessType": "CDN" }
]
}
}
字段说明
accessType 接入方式
| 取值 | 说明 |
|---|---|
DIRECT | 直接接入，DNS 解析到网关 IP，延迟最低 |
CDN | 走云开发 CDN 加速，即将下线，建议迁移到 EO |
CUSTOM | 自定义 CNAME 接入，需同时配 customCname |
EO | EdgeOne 边缘加速 |
protocol 协议类型
| 取值 | 说明 |
|---|---|
HTTP | 仅 HTTP |
HTTPS | 仅 HTTPS，需配 certId |
HTTP_AND_HTTPS | HTTP 与 HTTPS 双协议，默认 |
HTTP_TO_HTTPS | HTTP 自动 301 重定向到 HTTPS，生产环境推荐 |
HTTPS_TO_HTTP | HTTPS 自动 301 重定向到 HTTP |
其他字段：
customCname：accessType=CUSTOM时必填的 CNAME 解析记录值，需先在 DNS 服务商添加 CNAME 解析certId：域名级字段，只在域名首次创建时生效，已绑定域名不覆盖原值；protocol=HTTPS时必填enable：域名级开关，同域名分组下所有路由共享，以第一条路由的配置为准enablePathTransmission：hosting 路由未显式配pathRewrite时开启会与自动生成的重写冲突报错enableAuth：开启后请求需带身份凭证（SDK 登录后获取的 token 通过Authorization头透传）qpsPolicy：qpsTotal为全局 QPS 上限，qpsPerClient为单客户端上限，按ClientIP或UserID限频