在配置阿里云 CDN 的部分功能（如修改出站响应头、修改出站请求头等）时，可通过变量获取当前请求或响应的上下文信息（如请求方法、URL、客户端 IP 等），实现精细化的配置控制。本文介绍 CDN 支持的全部变量、各变量的取值示例及使用注意事项。
变量总览
CDN 变量按生效域分为接入域变量、回源域变量和响应变量：
接入域变量：在接入域（CDN节点处理客户端请求、生成缓存键）生效的变量。
回源域变量：在回源阶段生效的变量。部分功能部署在回源域模块上，此时接入域变量不生效，需使用回源域变量替换。
响应变量：可用于获取源站返回给CDN节点的响应头信息。
各生效域的变量分组与清单如下：
生效域 | 变量分组 | 变量 |
接入域 |
| |
接入域 |
| |
接入域 |
| |
接入域 |
| |
接入域 |
| |
接入域 |
| |
接入域 |
| |
接入域 |
| |
接入域 |
| |
接入域 |
| |
接入域 |
| |
接入域 |
| |
回源域 |
| |
回源域 |
| |
响应变量 |
|
支持使用变量的功能
接入域功能
回源域功能
使用限制
引用变量前，先确认以下跨变量的生效条件与限制：
SSL/TLS 相关变量仅适用于 HTTPS 请求，HTTP 请求中引用这些变量时取值为空。
$ssl_client_*系列变量仅在配置了客户端证书校验（双向认证/mTLS）的场景下有值，普通 HTTPS 请求中取值为空。GeoIP 解析存在精度限制，城市/经纬度级别字段通常定位到城市中心，不适合用于需要精确地理围栏的封禁类场景。当客户端 IP 无法识别时，相关字段返回默认值（如国家编码返回
XX，编码类数值返回0）。$uri可能被 CDN 内部跳转逻辑（如重定向、内部重写）修改，不推荐使用；如需获取未被修改的路径，使用$raw_uri。
Header 变量命名规范
处理 HTTP 请求头与响应头时，CDN 会将其自动映射为内部变量，变量命名必须遵循以下规则：
固定前缀：所有请求头变量必须以
$http_开头，所有响应头变量必须以$sent_http_开头。全小写转换：Header 名称中的所有大写字母必须转换为小写。
连字符替换：Header 名称中的连字符（
-）必须全部替换为下划线（_）。
转换示例：
原始 Header 名称 | 转换后的变量 |
Accept-Language |
|
X-Forwarded-For |
|
X-Customize-Header |
|
接入域变量
请求方法
$request_method
变量含义：当前请求使用的 HTTP 请求方法。
取值示例：
GET、POST、HEAD、PUT、DELETE等。
HTTP 版本
$server_protocol
变量含义：当前请求使用的 HTTP 协议版本。
取值示例：
HTTP/1.1、HTTP/2.0。
URI
$uri
变量含义：当前请求的 URL 路径，不包含查询参数。
取值示例：
/1.txt。注意事项：该值可能被 CDN 内部跳转逻辑（如重定向、内部重写）修改，不推荐使用；如需获取未被修改的路径，使用
$raw_uri。
$raw_uri
变量含义：原始请求的 URL 路径，不包含查询参数，不被 CDN 内部跳转逻辑修改。
取值示例：
/1.txt。
$request_uri
变量含义：原始请求的完整 URL 路径，包含查询参数。
取值示例：
/1.txt?chapter=1&flag=on。
请求参数
$args
变量含义：URL 中的完整查询参数字符串（不包含
?）。取值示例：
chapter=1&flag=on。
$arg_<参数名>
变量含义：URL 查询参数中特定参数的值，将
<参数名>替换为实际参数名即可。取值示例：
$arg_flag提取 URL/1.txt?chapter=1&flag=on中参数flag的值，结果为on。
请求头
$http_<请求头名>
变量含义：客户端请求中特定 HTTP 请求头的值，将
<请求头名>替换为实际请求头名称即可。取值示例：
$http_user_agent表示 User-Agent 请求头的值；$http_referer表示 Referer 请求头的值。注意事项：请求头变量的命名必须遵循 Header 变量命名规范。
域名
$host
变量含义：客户端请求的原始域名，即请求头
Host: <域名>的值。取值示例：
www.example.com。
请求协议
$scheme
变量含义：当前请求使用的协议类型。
取值示例：
http或https。
IP 地址与端口
$remote_addr
变量含义：客户端 IP 地址。
取值示例：
30.40.XX.XXX。
$remote_port
变量含义：客户端端口号。
取值示例：
63213。
$x_server_addr
变量含义：目的 IP 地址，即 CDN 节点对外的 VIP 地址。
取值示例：
122.228.XX.XXX。
$x_server_port
变量含义：目的端口，即 CDN 节点对外的服务端口。
取值示例：
80或443。
IP 归属地理位置与运营商
CDN 基于客户端 IP（$remote_addr）解析其归属的地理位置与运营商信息，变量取值基于 GeoIP 解析结果；解析存在精度限制，城市/经纬度级别字段通常定位到城市中心，不适合用于需要精确地理围栏的封禁类场景。当客户端 IP 无法识别时，相关字段返回默认值（如国家编码返回 XX，编码类数值返回 0）。同一维度提供编码（_id 后缀）与英文名称（_en 后缀）两种取值形式。
$ip_isp_id
变量含义：客户端 IP 所属运营商编码。
取值示例：电信为
100017。
$ip_isp_en
变量含义：客户端 IP 所属运营商英文名称。
取值示例：电信为
ChinaTelecom。
$ip_country_id
变量含义：客户端 IP 所属国家/地区编码。
取值示例：中国为
CN。
$ip_country_en
变量含义：客户端 IP 所属国家/地区英文名称。
取值示例：中国为
China。
$ip_region_id
变量含义：客户端 IP 所属地区或省份编码。
取值示例：广东省为
440000。
$ip_region_en
变量含义：客户端 IP 所属地区或省份英文名称。
取值示例：广东省为
guangdong。
$ip_city_id
变量含义：客户端 IP 所属城市编码。
取值示例：深圳市为
440300。
$ip_city_en
变量含义：客户端 IP 所属城市英文名称。
取值示例：深圳市为
shenzhen。
$ip_longitude
变量含义：客户端 IP 所属城市经度。
取值示例：深圳市为
114.05787。
$ip_latitude
变量含义：客户端 IP 所属城市纬度。
取值示例：深圳市为
22.54309。
SSL/TLS
SSL/TLS 变量提供 HTTPS 请求的会话信息。
本类变量仅适用于 HTTPS 请求，HTTP 请求中引用这些变量时取值为空。
$ssl_client_*系列变量还需预先配置客户端证书校验，普通 HTTPS 请求中取值为空。
$ssl_cipher
变量含义：当前请求使用的加密套件（密码算法组合）。
取值示例：
TLS_AES_256_GCM_SHA384。
$ssl_protocol
变量含义：当前请求使用的 SSL/TLS 协议版本。
取值示例：
TLSv1.3。
$ssl_client_cert
变量含义：客户端证书数据（返回证书内容）。
$ssl_client_raw_cert
变量含义：客户端证书的原始数据（用途与
$ssl_client_cert相同，保留证书原文）。
$ssl_client_serial
变量含义：客户端证书的序列号。
$ssl_verify
变量含义：客户端证书校验结果，校验成功时为
SUCCESS。取值示例：
SUCCESS。
$ssl_client_s_dn
变量含义：客户端证书的主题（Subject）DN。
$ssl_client_i_dn
变量含义：客户端证书的发行者（Issuer）DN。
节点名称
$hostname
变量含义：处理当前请求的 CDN 节点主机名。
取值示例：
cn2522（以实际节点命名为准）。
回源域变量
$scheme、$http_x_client_scheme、$proxy_scheme 均取协议类型（http 或 https），生效域与取值对象不同：
变量 | 生效域 | 含义 |
| 接入域 | 当前请求使用的协议类型 |
| 回源域 | 客户端发起请求时使用的协议类型（客户端 scheme） |
| 回源域 | CDN 节点回源时使用的协议类型（回源 scheme） |
协议
$http_x_client_scheme
变量含义：客户端发起请求时使用的协议类型（客户端 scheme）。
取值示例：
http或https。
$proxy_scheme
变量含义：CDN 节点回源时使用的协议类型（回源 scheme）。
取值示例：
http或https。
源站
$proxy_source
变量含义：当前请求实际回源的源站地址。
取值示例：
origin.example.com或192.0.2.1。
源站响应头
$sent_http_<响应头名>
变量含义：源站响应中特定 HTTP 响应头的值，将
<响应头名>替换为实际响应头名称即可。取值示例：
$sent_http_content_type表示源站响应Content-Type头的值，如text/html。注意事项：响应头变量的命名必须遵循 Header 变量命名规范。