跳到主要内容

tcb routes add

为指定域名创建一条或多条路由规则，把请求按「域名 + 路径」转发到云函数、云托管、静态托管等上游服务。

v3.0.0+

tcb routes 自 v3.0.0 起提供。

语法​

tcb routes add --data '<JSON>' [options]

参数​

参数必填说明默认值
--data <json>是路由配置 JSON—
-e, --env-id <envId>否环境 ID配置文件 envId

配置格式​

{
  "domain": "api.example.com",
  "routes": [
    {
      "path": "/api",
      "upstreamResourceType": "CBR",
      "upstreamResourceName": "my-service",
      "upstreamResourceVersion": "可选，仅云函数支持",
      "enable": true,
      "enableAuth": false,
      "enableSafeDomain": true,
      "enablePathTransmission": false,
      "pathRewrite": { "prefix": "/newpath" },
      "qpsPolicy": {
        "qpsTotal": 500,
        "qpsPerClient": { "limitBy": "ClientIP", "limitValue": 20 }
      }
    }
  ]
}
字段类型必填说明
domainstring是目标域名，需已通过 tcb domains add 绑定
routes[].pathstring是路由路径，以 / 开头，不支持通配符。每段仅允许字母、数字、.、_、-，每段不超过 50 字符；不可使用保留前缀 /__auth、/.well-known
routes[].upstreamResourceTypestring是SCF（云函数）、CBR（云托管）、STATIC_STORE（静态托管）、WEB_SCF（Web 云函数）、LH（轻量应用服务器）
routes[].upstreamResourceNamestring是上游服务名称
routes[].upstreamResourceVersionstring否上游版本，仅 SCF / WEB_SCF 支持，取值见转发版本；缺省按 $DEFAULT 处理（v3.8.10+）
routes[].enableboolean否是否启用路由，默认 true
routes[].enableSafeDomainboolean否是否开启安全域名校验，默认 true

enableAuth / enablePathTransmission / pathRewrite / qpsPolicy 的权威定义见配置文件-网关。命令式与声明式的差异：

  • pathRewrite：命令式仅支持 prefix；声明式额外支持 staticStorePrefix
  • qpsPolicy：qpsTotal 命令式上限 500、声明式 100–100000；qpsPerClient.limitValue 声明式上限 30
  • enableAuth / enablePathTransmission：两种方式语义一致

示例​

# 转发到云托管服务
tcb routes add -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/api","upstreamResourceType":"CBR","upstreamResourceName":"my-service"}]}'

# 转发到云函数并开启身份认证
tcb routes add -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/func","upstreamResourceType":"SCF","upstreamResourceName":"my-function","enableAuth":true}]}'

# 静态网站根路径
tcb routes add -e <envId> --data '{"domain":"www.example.com","routes":[{"path":"/","upstreamResourceType":"STATIC_STORE","upstreamResourceName":"website"}]}'

# 带 QPS 限流
tcb routes add -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/v1","upstreamResourceType":"CBR","upstreamResourceName":"backend","qpsPolicy":{"qpsTotal":1000,"qpsPerClient":{"limitBy":"ClientIP","limitValue":50}}}]}'

# 一次创建多条路由
tcb routes add -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/v1","upstreamResourceType":"SCF","upstreamResourceName":"func-v1"},{"path":"/v2","upstreamResourceType":"CBR","upstreamResourceName":"service-v2"}]}'

# 转发到云函数的指定版本
tcb routes add -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/func-v2","upstreamResourceType":"SCF","upstreamResourceName":"my-function","upstreamResourceVersion":"2"}]}'

注意事项​

  • path 不支持通配符（/api/*、/* 会被拒绝）。需要匹配一级路径下的所有子路径时，配置多条精确路径路由（如 /api、/api/v1）
  • STATIC_STORE 只支持一级路径（如 / 或 /static），多级路径会被拒绝
  • 同一域名下不能有重复路径，重复会报 INVALID_PARAM；调整已有路由用 tcb routes edit
  • 命令式创建要求域名已通过 tcb domains add 绑定；声明式 tcb deploy 会自动绑定域名