跳到主要内容

配置文件-网关

cloudbaserc.json 中的 gateway 字段用于 tcb deploy 声明式部署网关，定义如何将 HTTP 请求按「域名 + 路径」转发到云函数、静态托管等上游服务。

属性值
类型Object
说明CloudBase 网关路由配置，用于 tcb deploy 声明式部署网关

子字段​

字段类型必填说明
routesArray<Object>是网关路由列表

routes[] 字段​

字段类型必填默认值说明
pathString是—URL 路径，如 /api。必须以 / 开头，不支持通配符 *，每段仅允许字母/数字/./_/-，每段 ≤ 50 字符；不可使用系统保留前缀 /__auth、/.well-known
targetString是—目标资源：function:<name>（云函数）或 hosting:<name>（静态托管）。云函数自动区分类型：HTTP 型 → WEB_SCF 路由、Event 型 → SCF 路由（两种均可）；hosting 只支持一级路径（如 / 或 /web），多级路径报错
domainString否环境默认域名绑定的自定义域名。未绑定时 tcb deploy 自动绑定（幂等），无需先执行 tcb domains add
certIdString否—SSL 证书 ID。显式配置优先；未配置且域名未绑定时自动按域名匹配已签发证书（仅 Status=1 未过期），匹配不到则部署报错
accessTypeString否DIRECT域名接入方式：DIRECT（直接接入）/ CDN（云开发 CDN，即将下线）/ CUSTOM（自定义接入，需配 customCname）/ EO（EdgeOne）
customCnameString否—accessType=CUSTOM 时必填的 CNAME 记录
protocolString否HTTP_AND_HTTPS域名协议：HTTP / HTTPS / HTTP_AND_HTTPS / HTTP_TO_HTTPS（http 重定向 https）/ HTTPS_TO_HTTP
enableBoolean否true域名启用状态（作用于域名绑定，取该域名分组第一条路由的配置；路由本身始终启用）
pathRewriteObject否—路径重写：{ "prefix": "/newpath" } 或 { "staticStorePrefix": "/xxx" }。prefix 与 staticStorePrefix 只能填一个；hosting 路由未配置时自动生成 prefix=对应 hosting 的部署路径
enablePathTransmissionBoolean否false路径透传：true=完整路径传到上游，false=只传匹配后路径。⚠️ hosting 路由未显式配置 pathRewrite 时开启会与自动生成的重写冲突报错
enableAuthBoolean否false是否开启身份认证
qpsPolicyObject否—QPS 限频：{ "qpsTotal": 100-100000, "qpsPerClient": { "limitBy": "ClientIP" | "UserID", "limitValue": 0-30 } }。qpsPerClient 的 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 边缘加速
  • customCname：accessType=CUSTOM 时必填的 CNAME 解析记录值，需先在 DNS 服务商添加 CNAME 解析
  • protocol 协议类型：
    • HTTP：仅 HTTP
    • HTTPS：仅 HTTPS（需配 certId）
    • HTTP_AND_HTTPS：HTTP 和 HTTPS 双协议（默认）
    • HTTP_TO_HTTPS：HTTP 自动 301 重定向到 HTTPS（生产环境推荐）
    • HTTPS_TO_HTTP：HTTPS 自动 301 重定向到 HTTP
  • certId：SSL 证书 ID。域名级字段——只在域名首次创建时生效；已绑定域名不覆盖原值。protocol=HTTPS 时必填
  • enable：域名级开关（不是路由级），同域名分组下所有路由共享此配置，以第一条路由的配置为准
  • enablePathTransmission：路径透传。⚠️ hosting 路由未显式配 pathRewrite 时开启会与自动生成的重写冲突报错
  • enableAuth：开启后请求需带身份凭证（SDK 登录后获取的 token 通过 Authorization 头透传）
  • qpsPolicy 限频：
    • qpsTotal：全局 QPS 上限（100-100000）
    • qpsPerClient：单客户端 QPS 上限（0-30），按 ClientIP（IP 维度）或 UserID（用户维度）限频

相关命令​