跳到主要内容

缓存配置

HTTP 网关支持为自定义域名配置缓存规则：按请求特征匹配（URL 路径、文件扩展名、完整 URI），并自定义缓存动作——可控制边缘节点与浏览器的缓存时长，或自定义缓存键策略，以提升资源访问速度、降低源站压力。

适用范围

缓存规则只在自定义域名上生效。开启缓存前，请确保自定义域名已开启边缘加速，或此前以云开发 CDN 方式接入（该接入方式已不再支持新接入，仅存量域名可用）。

配置入口​

进入 云开发平台 → HTTP 网关 → 缓存配置，按域名维度维护一组缓存规则列表。

每个域名最多 3 条规则，列表下方的规则优先级最高。匹配按列表自下而上进行，首个命中的规则生效。每条规则对应 1 个匹配条件（目标 + 方式 + 值列表）+ 1 个操作。控制台支持拖拽排序：拖动规则左侧的拖拽手柄，可调整规则的优先级顺序；调整后必须点击右上角的「保存」按钮，排序才会生效。

缓存配置

整体结构​

域名 Domain
 └─ 缓存配置 Cache
      └─ Rules[]（规则列表，数组顺序即优先级，越靠后越优先）
           ├─ Condition：这条规则「对哪些请求」生效
           └─ Actions ：命中后「怎么缓存」

理解这句话就够了：当一次请求进来，从 Rules 第一条开始往下找，第一个 Condition 命中的规则生效，然后执行它的 Actions。

支持的匹配条件​

每条规则的「匹配条件」下拉里选择一种目标 + 一种匹配方式 + 一组值。控制台提供三档目标，对应 Condition.Target：

控制台目标对应 Target匹配对象
URL 路径url_path请求路径（不含 ? 后的查询串）
文件扩展名file_extension文件扩展名（如 css、jpg）
完整 URIfull_uri完整 URI（路径 + 查询串）

匹配方式通过 Condition.MatchType 指定：

MatchType含义
prefix前缀匹配（如 /static/ 开头）
suffix后缀匹配（如 .png 结尾）
contains包含匹配
exact精确匹配

Condition.Values 是一个字符串数组，任一命中即生效（OR 语义），最多 100 条，单项 1~1024 字节。

约束：每条规则仅可设置 1 个匹配条件（目标 + 方式 + 值列表）。

缓存动作​

每条规则在「缓存动作」下拉里选择一种动作，控制台只提供两类动作，对应 Actions.Type：

控制台动作对应 Type作用
自定义缓存Cache控制边缘节点和浏览器的缓存时长
自定义 Cache KeyCacheKey自定义「什么样的请求算同一个缓存」（需开启边缘加速）
备注

CacheKey 动作仅在已开启边缘加速的域名上生效。云开发 CDN 接入方式（存量）不支持。

动作一：自定义缓存（Type=Cache）​

选择「自定义缓存」后，提供了三种互斥的缓存策略，必须三选一：

策略 A：不缓存​

适用于每次必须拿最新结果的请求，例如动态接口、实时数据。

{ "Type": "Cache", "Cache": { "NoCache": true } }

效果：响应头携带 Cache-Control: no-cache，节点和浏览器都不缓存。

策略 B：自定义时长​

分别控制边缘节点和浏览器的缓存时长，常用于静态资源（图片、CSS、JS、字体等）。

{
  "Type": "Cache",
  "Cache": {
    "CacheTime": 86400,    // 边缘节点缓存 1 天
    "MaxAgeTime": 3600     // 浏览器缓存 1 小时
  }
}

两个时间别搞混：

字段控制对象对应响应头
CacheTime边缘节点（边缘加速 / CDN）s-maxage
MaxAgeTime用户浏览器max-age

取值范围：[0, 31536000]（0 秒 ~ 1 年），可只设其中一个。

策略 C：跟随源站​

源站（云函数 / 静态托管）已经在响应头里给了 Cache-Control，不想在边缘再覆盖一层，就交给源站说了算。

{ "Type": "Cache", "Cache": { "FollowOrigin": true } }

效果：节点和浏览器缓存时长都遵循源站返回的 Cache-Control。

动作二：自定义 Cache Key（Type=CacheKey）​

选择「自定义 Cache Key」后，可以告诉边缘节点：哪些参数应该忽略、哪些参数必须区分，让同一份资源更高效命中同一份缓存。

默认情况下，URL 带不同查询参数会被当作不同缓存，例如 page.html?a=1 和 page.html?a=2 各存一份。

查询参数处理通过 QueryStringAction 提供两种策略：

QueryStringAction含义
includeCustom白名单：只有列出的参数参与缓存键，其余忽略
excludeCustom黑名单：列出的参数被忽略，其余参数参与

示例：忽略埋点参数，让同一份资源命中同一份缓存：

{
  "Type": "CacheKey",
  "CacheKey": {
    "FullURLCache": "off",
    "QueryStringSwitch": "on",
    "QueryStringAction": "excludeCustom",
    "QueryStringValues": ["debug", "from"]
  }
}

两条约束：

  • FullURLCache=on 与 QueryStringSwitch=on 互斥，不能同时开。
  • QueryStringSwitch=on 时，QueryStringAction 必填。

同一规则内「自定义缓存」和「自定义 Cache Key」两种动作可以叠加：例如同时设置「自定义时长（静态资源缓存 1 天）+ 自定义 Cache Key（忽略埋点参数）」。

配置示例​

下面 5 个典型场景演示如何使用上述两类动作组合出实际可用的配置。

场景 1：缓存静态资源，让用户加载更快​

「自定义缓存 → 自定义时长」：

{
  "Description": "缓存静态资源",
  "Enable": true,
  "Condition": {
    "Target": "file_extension",
    "MatchType": "exact",
    "Values": ["jpg", "png", "gif", "css", "js", "svg", "woff2"]
  },
  "Actions": [
    {
      "Type": "Cache",
      "Cache": {
        "CacheTime": 86400,
        "MaxAgeTime": 3600
      }
    }
  ]
}

场景 2：动态接口、实时数据不缓存​

「自定义缓存 → 不缓存」：

{
  "Description": "接口不缓存",
  "Enable": true,
  "Condition": {
    "Target": "url_path",
    "MatchType": "prefix",
    "Values": ["/api/"]
  },
  "Actions": [
    { "Type": "Cache", "Cache": { "NoCache": true } }
  ]
}

场景 3：缓存策略完全听源站的​

「自定义缓存 → 跟随源站」：

{
  "Condition": {
    "Target": "url_path",
    "MatchType": "prefix",
    "Values": ["/src/"]
  },
  "Actions": [
    { "Type": "Cache", "Cache": { "FollowOrigin": true } }
  ]
}

场景 4：忽略埋点参数，让同一份资源命中同一份缓存​

「自定义 Cache Key → 黑名单」：HTML 文件本来按 URL 不同各存一份，忽略 debug、from 后，所有带这两个埋点参数的请求都共用同一份缓存。

{
  "Description": "忽略 debug、from 参数",
  "Condition": {
    "Target": "url_path",
    "MatchType": "suffix",
    "Values": [".html"]
  },
  "Actions": [
    {
      "Type": "CacheKey",
      "CacheKey": {
        "FullURLCache": "off",
        "QueryStringSwitch": "on",
        "QueryStringAction": "excludeCustom",
        "QueryStringValues": ["debug", "from"]
      }
    }
  ]
}

场景 5：同一份资源保留版本化参数​

「自定义缓存（自定义时长）+ 自定义 Cache Key（白名单）」组合：只让 v、lang 这两个参数参与缓存键，其余忽略，同时缓存 1 天。

{
  "Description": "保留版本化参数",
  "Enable": true,
  "Condition": {
    "Target": "file_extension",
    "MatchType": "exact",
    "Values": ["js", "css"]
  },
  "Actions": [
    {
      "Type": "Cache",
      "Cache": {
        "CacheTime": 86400,
        "MaxAgeTime": 3600
      }
    },
    {
      "Type": "CacheKey",
      "CacheKey": {
        "FullURLCache": "off",
        "QueryStringSwitch": "on",
        "QueryStringAction": "includeCustom",
        "QueryStringValues": ["v", "lang"]
      }
    }
  ]
}

含义：只有 v、lang 这两个参数不同才算不同缓存，其余参数忽略。

字段速查表​

字段类型说明
RulesHTTPServiceCacheRule[]规则列表，数组顺序即优先级，越靠后越优先

单条规则​

字段类型必填说明
Descriptionstring否描述，最多 128 字节
Enableboolean否开关，true / 不传启用，false 禁用
ConditionHTTPServiceRuleCondition是匹配条件
ActionsHTTPServiceCacheAction[]否缓存动作列表，同一规则内相同 Type 至多一个

缓存动作 Actions​

字段类型说明
TypestringCache（自定义缓存）或 CacheKey（自定义 Cache Key）
CacheHTTPServiceCacheParamsType=Cache 时必填
CacheKeyHTTPServiceCacheKeyParamsType=CacheKey 时必填

同一规则内相同 Type 至多一个。

缓存参数 Cache​

三个互斥开关，必须三选一：

组合字段效果
不缓存NoCache: true节点 + 浏览器都不缓存（策略 A）
自定义时长CacheTime 和/或 MaxAgeTime分别控制节点、浏览器缓存秒数（策略 B）
跟随源站FollowOrigin: true节点 + 浏览器都听源站的 Cache-Control（策略 C）

CacheTime / MaxAgeTime 取值范围：[0, 31536000]（0 秒到 1 年）。

缓存键参数 CacheKey​

字段可选值含义
FullURLCacheon / off是否把整个 URL（含参数）都作为缓存键
QueryStringSwitchon / off查询参数是否参与缓存键
QueryStringActionincludeCustom白名单：只有列出的参数参与缓存键
excludeCustom黑名单：列出的参数被忽略
QueryStringValues字符串数组参数名列表，最多 100 项，单项 1~128 字节

两条约束：

  • FullURLCache=on 与 QueryStringSwitch=on 互斥，不能同时开。
  • QueryStringSwitch=on 时，QueryStringAction 必填。

完整配置示例​

下面是一个同时覆盖动态接口与静态资源的典型配置：

{
  "Domain": "your-domain.com",
  "Extension": {
    "Cache": {
      "Rules": [
        {
          "Description": "静态资源缓存",
          "Enable": true,
          "Condition": {
            "Target": "file_extension",
            "MatchType": "exact",
            "Values": ["jpg", "png", "css", "js", "svg"]
          },
          "Actions": [
            {
              "Type": "Cache",
              "Cache": { "CacheTime": 86400, "MaxAgeTime": 3600 }
            }
          ]
        },
        {
          "Description": "接口不缓存",
          "Enable": true,
          "Condition": {
            "Target": "url_path",
            "MatchType": "prefix",
            "Values": ["/api/"]
          },
          "Actions": [{ "Type": "Cache", "Cache": { "NoCache": true } }]
        }
      ]
    }
  }
}
规则优先级

上面把「静态资源缓存」放在「接口不缓存」之前。因为列表下方的规则优先级最高，排在后面的「接口不缓存」规则先生效；/api/ 下的 .js 请求被该 NoCache 规则拦截，避免接口脚本被误缓存。

验证配置是否生效​

  1. 查配置：调用 DescribeHTTPServiceRoute，看返回的 Domain.Extension.Cache 是否和你提交的一致。
  2. 看响应头：对目标资源发请求，检查 Cache-Control：
    • max-age=3600 ← 来自 MaxAgeTime
    • s-maxage=86400 ← 来自 CacheTime
  3. 看命中：连续请求两次，eo-cache-status 从 MISS 变 HIT，说明边缘缓存真正工作。

刷新缓存​

配置好缓存规则后，源站更新（如静态资源重新发布、API 内容变更）不会自动反映到边缘节点，因为边缘缓存仍在按规则生效。需要主动刷新缓存，让边缘节点下次请求时回源拉取最新内容。

进入 云开发平台 → HTTP 网关 → 缓存配置 → 刷新缓存 Tab。

刷新方式​

字段类型说明
域名必选选择要刷新的自定义域名
缓存类型必选边缘加速（自定义域名启用边缘加速后的边缘节点缓存）或 CDN 缓存（存量）（旧版云开发 CDN 接入方式的缓存，新接入不再使用）
刷新方式URL / 目录单文件 URL 刷新，或按目录前缀批量刷新
内容必填URL 列表或目录前缀，按所选刷新方式填入

适用场景​

  • 静态资源更新：重新部署后，用 URL 刷新让所有边缘节点拉取新版本。
  • 批量回滚：用目录刷新一次性让整目录重新回源。
  • 故障修复：线上发现某资源缓存了错误版本，立即 URL 刷新。
备注

刷新仅清理边缘节点缓存，不会影响浏览器本地缓存。如需强制用户立即看到最新内容，需要同步配合 Cache-Control: no-cache 或版本号/文件名变更。

查看刷新记录​

切换到 历史记录 Tab，可按时间段筛选查询历史刷新任务：

字段说明
时间任务提交时间
任务 ID后台任务唯一标识
域名被刷新的域名
缓存类型边缘加速 / CDN 缓存（存量）
刷新方式URL / 目录
刷新目标URL 或目录前缀
状态处理中 / 成功 / 失败
创建时间同「时间」字段

相关文档​