You need to enable JavaScript to run this app.
导航
内容分发网络
  • 文档首页
    • /内容分发网络/用户指南/域名管理/域名配置管理/缓存配置/缓存键值
缓存键值
最近更新时间：2025.11.04 19:31:39首次发布时间：2022.02.09 10:17:09
复制全文
我的收藏
有用
有用
无用
无用

本文档介绍如何在火山引擎内容分发网络（CDN）中通过创建缓存键规则来配置缓存键。

缓存键概述

缓存键是缓存中每个文件的唯一标识。通常情况下，缓存键包含用户请求 URL 中的 hostname、路径和查询参数。您可以对缓存键中的查询参数进行配置。

  • 当收到用户请求时，CDN 会为所请求的文件生成一个缓存键，然后尝试将该缓存键与每个缓存文件的缓存键进行匹配。如果 CDN 找到一个匹配，则表示该请求命中了缓存。需要留意的是，缓存键的匹配过程是大小写敏感的。
  • 当缓存一个文件时，CDN 会使用该文件的缓存键来标记这个文件。

缓存键配置

CDN 提供了缓存键配置的功能。您可以在控制台中创建缓存键规则。缓存键规则影响缓存命中率，因为 CDN 基于缓存键来匹配用户请求和已缓存的文件。

配置缓存键有以下两种方式：

  • 常规方式：在域名配置页面，您可以创建缓存键规则，指定缓存键包含的查询参数。本文主要介绍这种方式。
  • 规则引擎：您也可以在规则引擎中配置缓存键。规则引擎提供了更丰富的配置项。除了查询参数，您还可以：
    • 设置缓存键中包含的请求头。
    • 设置缓存键中包含的 Cookie。
    • 改写缓存键中文件的路径。
    • 指定缓存键中的文件路径是否区分大小写。
      更多信息，参见 规则引擎。

说明

默认情况下，缓存键包含所有查询参数，但不包含任何 Cookie 和请求头。

在本文最后，我们提供了一个 配置示例 帮助您更好理解缓存键设置对于缓存命中的影响。

使用场景

如果您站点上文件 URL 中的查询参数并不是用来区分文件的，您可以通过创建缓存键规则来指定 CDN 在生成的缓存键中需要丢弃的查询参数，以提高缓存命中率，减少回源请求。例如，URL 中包含了 auth 参数。其目的是用来验证用户的身份，不是用来区分文件。在这个情况下，该参数就无需包含在生成的缓存键中。

操作步骤

  1. 登录 火山引擎内容分发网络控制台。
  2. 在左侧导航栏，点击 域名管理。
  3. 在 域名管理 页面，找到需要配置的域名，点击 管理。
  4. 定位 缓存键值 模块。
    • 如果您使用的是旧版域名管理页面，点击 编辑配置，然后在 缓存配置 标签页中定位 缓存键值 模块。
    • 如果您使用的是新版域名管理页面，点击 编辑域名。在页面左侧的树状配置项列表中，定位 功能配置 > 缓存配置 > 缓存键值。
      关于新旧版域名管理页面的区别，参见 新版域名配置。
  5. 在 缓存键值 模块中，点击 新增规则。您最多可以添加 50 条规则。
  6. 根据 配置说明 进行设置。
  7. 配置完成后，点击 提交编辑。

Image

预设缓存键值规则

在您添加域名时，CDN 会默认为您添加一条缓存键值规则。该规则对所有文件的请求生效。您可以修改该规则的配置，但是无法删除该规则。在您添加其他缓存键值规则时，这条规则的优先级始终是最低的，其确保了任何请求都可以匹配到一条规则。
Image

配置说明

配置

说明

规则类型

表示规则中的过滤条件。该配置有以下选项：

  • 文件后缀：表示路径末尾的扩展名。
  • 文件目录：表示路径中的目录。
  • 文件全路径：表示请求 URL 中的路径。
  • 全路径正则表达式：表示请求 URL 中的路径，通过正则表达式匹配。 要指定该选项，请 提交工单。

忽略大小写匹配

表示 CDN 在查询缓存以及匹配请求时，规则内容 是否是大小写敏感的。

规则内容

表示规则中的过滤值。多个过滤值之间使用分号（;）分隔，总长度不能超过 1,024 个字符，不能包含以下字符：

  • 连续斜杠（//）、空格、美元符号（$）、问号（?）、Delete（ASCII code 127）。

CDN 在尝试将规则中的过滤条件与用户请求匹配时，匹配过程是大小写不敏感的。

另外，

  • 如果 规则类型 是 文件后缀，过滤值是一个或者多个文件后缀。文件后缀无需以句点（.）开头。例如：png;txt。
  • 如果 规则类型 是 文件目录，过滤值是一个或者多个目录路径。目录路径必须以斜杠（/）开头和结尾。例如：/chs/foods/;/us/birds/。
  • 如果 规则类型 是 文件全路径，过滤值是一个或者多个文件路径。文件路径必须以斜杠（/）开头，可以包含星号（*）用来表示一个或者多个字符。例如：/chs/foods/local*sets;/us/birds/chickadee。
  • 如果 规则类型 是 全路径正则表达式，过滤值是一个或者多个正则表达式，用于匹配请求路径中的任意字符串。例如：^/a{1,2}.*g$。

参数设置

表示 CDN 在生成的缓存键中包含哪些请求 URL 中的查询参数。该配置的取值如下：

  • 保留全部参数：表示缓存键中包含请求 URL 中全部的查询参数。
  • 删除全部参数：表示缓存键中不包含请求 URL 中任何的查询参数。
  • 删除指定参数：表示缓存键中包含请求 URL 中全部的查询参数，除了 参数名称 中指定的查询参数。
  • 保留指定参数：表示如果用户请求 URL 中存在 参数名称 中指定的查询参数，那么缓存键中包含这些指定的查询参数。

参数忽略大小写

表示 CDN 在查询缓存以及匹配请求时，参数名称 是否是大小写敏感的。该配置仅当 参数设置 是 删除指定参数 或者 保留指定参数 时有效。

例子：您指定保留的参数是 size，参数忽略大小写 为开启。然后，CDN 收到了一个 URL 包含 SIZE 参数的请求。在这个情况下，CDN 会在请求文件的缓存键中保留 SIZE 参数。

参数名称

表示需要保留或者丢弃的查询参数。参数名称可以包含字母、数字、中划线（-）、下划线（_)、句号（.）、逗号（,）、感叹号（!）。多个查询参数用英文分号（;）分隔。例如 version;size。

  • 如果 参数设置 是 保留全部参数 或者 删除全部参数，该配置的值必须是 *。* 表示全部查询参数。
  • 如果 参数设置 是 删除指定参数 或者 保留指定参数，您可以指定一个或者多个查询参数，但是您不能指定 *。同时，您指定的查询参数不能包含连续斜杠（//）、百分号（%）、空格。

该配置的默认值是 *。

规则优先级

在规则列表中，每条规则都有优先级。优先级为 1 的规则具有最高优先级。当收到一个用户请求时，CDN 按规则的优先级，从高到低尝试将请求与规则匹配。如果请求匹配了一条规则，匹配过程就停止了。您可以拖动规则来调整优先级。需要留意的是，您无法调整那条预设规则的优先级。

更多信息

配置示例

  • 您站点根目录下的文件 URL 中包含 version，token 这两个参数。
  • 这两个参数中，只有 version 是用来区分文件的。例如 /image.png?version=1 与 /image.png?version=2 是两个不同的文件。但是 /image.png?version=1&token=abc 与 /iamge.png?version=1&token=xyz 是相同的文件。
  • CDN 先后收到两个该文件的请求。请求 URL 分别是 https://<domain>/image.png?version=1&token=12345 和 https://<domain>/image.png?version=1&token=abcde。

未创建缓存键值规则的结果

在收到第一个请求时，CDN 缓存该文件。该文件在缓存中的缓存键是 /image.png?version=1&token=12345。在收到第二个请求时，CDN 会使用 /image.png?version=1&token=abcde 去匹配缓存中的文件。由于没有命中缓存，CDN 会向源站请求该文件。