var: 通过预定义函数动态变量赋值

安装

您可以在任何基于 RHEL 的发行版中安装此模块，包括但不限于：

RedHat Enterprise Linux 7、8、9 和 10
CentOS 7、8、9
AlmaLinux 8、9
Rocky Linux 8、9
Amazon Linux 2 和 Amazon Linux 2023

CentOS/RHEL 8+、Fedora Linux、Amazon Linux 2023+CentOS/RHEL 7 和 Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-var

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-var

通过在 /etc/nginx/nginx.conf 的顶部添加以下内容来启用该模块：

load_module modules/ngx_http_var_module.so;

本文档描述了 nginx-module-var v0.1.1，于 2026 年 2 月 23 日发布。

server {
    listen 127.0.0.1:8080;
    server_name localhost;

    location / {
        var $new_var set $scheme://$host$request_uri;
    }
}

指令

var

语法: var $new_variable function [-i] args... [if\=condition]

默认: -

上下文: http, server, location

定义一个新变量，其值为函数计算的结果。变量值不能被缓存，每次使用时都会重新计算。

如果当前级别未定义同名变量，则可以从上一级继承。

-i 参数用于忽略大小写（仅在某些函数中可用）。

除了函数名称、-i 参数和正则表达式外，所有参数都允许包含变量。

当参数的值无效时，变量的值为空。在布尔函数中，无效参数也会导致空值而不是 0。

var 不能与 map 或 geo 指令同时定义同一变量。然而，可以使用 set 指令覆盖由 var 定义的变量。

以下函数可用：

#### 条件判断 ####
# 如果输入参数为空或 0，则返回 1，否则返回 0
var $bool_var not str;

# 如果所有输入参数都非空且不为 0，则返回 1，否则返回 0
var $bool_var and str1 str2...;

# 如果任何输入参数非空且不为 0，则返回 1，否则返回 0
var $bool_var or str1 str2...;


#### 字符串判断 ####
# 检查字符串是否为空，返回 1 或 0
var $bool_var is_empty str;

# 检查字符串是否非空，返回 1 或 0
var $bool_var is_not_empty str;

# 检查字符串是否为数字，返回 1 或 0。仅允许十进制数字，支持负数和分数。
var $bool_var is_num str;

# 检查字符串是否相等，返回 1 或 0
var $bool_var str_eq [-i] str1 str2;

# 检查字符串是否不相等，返回 1 或 0
var $bool_var str_ne [-i] str1 str2;

# 检查字符串是否具有指定前缀，返回 1 或 0
var $bool_var starts_with [-i] str prefix;

# 检查字符串是否具有指定后缀，返回 1 或 0
var $bool_var ends_with [-i] str suffix;

# 检查子字符串是否存在，返回 1 或 0
var $bool_var contains [-i] str sub_str;

# 检查 str1 是否在 str2 .. strn 中，返回 1 或 0
var $bool_var str_in [-i] str1 str2 str3 .. strn;

#### 一般字符串操作 ####
# 直接设置变量的值
var $new_var set src_str;

# 字符串长度
var $new_var len src_str;

# 转换为大写
var $new_var upper src_str;

# 转换为小写
var $new_var lower src_str;

# 将每个单词的首字母大写（单词由非字母数字字符分隔）
var $new_var initcap src_str;

# 修剪前导和尾随空格字符或其他字符
var $new_var trim src_str [char];

# 修剪前导空格字符或其他字符
var $new_var ltrim src_str [char];

# 修剪尾随空格字符或其他字符
var $new_var rtrim src_str [char];

# 反转字符串
var $new_var reverse src_str;

# 获取子字符串的起始位置
var $new_var position [-i] src_str sub_str;

# 重复字符串指定次数
var $new_var repeat src_str times;

# 提取子字符串
var $new_var substr src_str start [len];

# 替换关键字
var $new_var replace [-i] src_str src dst;

# 提取参数
# 从参数列表中提取值。此用例用于提取查询参数，而无需编写正则表达式，但也可以用于查找任何名称/值对列表中的值。如果参数存在多个实例，仅返回第一个。变量将获得空值。参数名称和值之间的分隔符默认为 '='，参数分隔符默认为 '&'。
var $new_var extract_param [-i] param_name src_string [separator] [delimiter];

# 示例：查询 "foo=123&bar=456&baz=789"。如果参数名称是 bar 且分隔符是 &，则结果变量值将为 456。
# var $extraed_arg_bar extract_param bar "foo=123&bar=456&baz=789" & =;

#### JSON 操作 ####
# 从有效的 JSON 字符串中提取 JSON 值。
# 需要安装 cJSON 库（请参见安装部分）
var $new_var extract_json json subkey1 [subkey2] [subkey3] ...;

# 支持嵌套对象键和数组索引 [n]
# 返回不带引号的字符串值，其他类型作为 JSON 字符串
# 数组和对象以紧凑的 JSON 字符串返回

# 示例：
# 从嵌套对象中提取
# var $new_var extract_json '{"a":{"b":{"c":3}}}' a b c;
# 结果：3

# 使用 [index] 从数组中提取
# var $new_var extract_json '{"users":[{"name":"Alice"},{"name":"Bob"}]}' users [0] name;
# 结果：Alice

# 将数组提取为 JSON 字符串
# var $items extract_json '{"data":[1,2,3]}' data;
# 结果：[1,2,3]

# 将对象提取为 JSON 字符串
# var $user extract_json '{"user":{"name":"Bob","age":30}}' user;
# 结果：{"name":"Bob","age":30}


#### 正则判断 ####
# 检查正则表达式是否匹配，返回 1 或 0
var $bool_var regex_match [-i] src_str match_regex;


#### 正则操作 ####
# 捕获正则表达式
var $new_var regex_capture [-i] src_str regex assign_value;

# 替换正则表达式
var $new_var regex_sub [-i] src_str regex replacement;


#### 数学判断 ####
# 检查数字是否相等，返回 1 或 0
var $bool_var eq num1 num2;

# 检查数字是否不相等，返回 1 或 0
var $bool_var ne num1 num2;

# 检查是否小于，返回 1 或 0
var $bool_var lt num1 num2;

# 检查是否小于或等于，返回 1 或 0
var $bool_var le num1 num2;

# 检查是否大于，返回 1 或 0
var $bool_var gt num1 num2;

# 检查是否大于或等于，返回 1 或 0
var $bool_var ge num1 num2;

# 检查是否在 start_num 和 end_num 范围内，如果未指定 end_num，范围为 [0, start_num]，返回 1 或 0
var $bool_var range num start_num [end_num];

# 检查数字是否为 num2 .. numn 之一，返回 1 或 0
var $bool_var in num1 num2 .. numn;

### 数学操作 ####
# 绝对值（返回原始格式，不带负号）
var $new_var abs num;

# 最大值（返回原始格式）
var $new_var max num1 num2;

# 最小值（返回原始格式）
var $new_var min num1 num2;

# 整数加法
var $new_var add int1 int2;

# 整数减法
var $new_var sub int1 int2;

# 整数乘法
var $new_var mul int1 int2;

# 整数除法，int2 不能为 0
var $new_var div int1 int2;

# 整数取模，int2 不能为 0
var $new_var mod int1 int2;

# 按位与操作
var $new_var bitwise_and int1 int2;

# 按位非操作
var $new_var bitwise_not int;

# 按位或操作
var $new_var bitwise_or int1 int2;

# 按位异或操作（排他或）
var $new_var bitwise_xor int1 int2;

# 左移操作，shift_bits 必须 >= 0
var $new_var lshift int shift_bits;

# 右移操作（算术移位，保留符号位），shift_bits 必须 >= 0
var $new_var rshift int shift_bits;

# 无符号右移操作（逻辑移位，零填充），shift_bits 必须 >= 0
var $new_var urshift int shift_bits;

# 四舍五入到 n 位有效数字
var $new_var round src_num int;

# 直接截断小数部分（不四舍五入）
var $new_var int src_num;

# 向下取整，返回小于或等于源的最大整数
var $new_var floor src_num;

# 向上取整，返回大于或等于源的最小整数
var $new_var ceil src_num;

# 随机正整数，范围为 [start_int, end_int]，如果未指定 end_int，范围为 [0, start_int]
var $new_var rand [start_int] [end_int];

# 指定字节数的随机十六进制序列，number_of_bytes 必须为 1-32，默认值为 32
var $new_var hexrand [number_of_bytes];


#### 编码和解码 ####
# 将二进制转换为十六进制
var $new_var hex_encode src_str;

# 将十六进制转换为二进制
var $new_var hex_decode src_str;

# 十进制转换为十六进制
var $new_var dec_to_hex dec;

# 十六进制转换为十进制
var $new_var hex_to_dec hex;

# 完整 URI 编码
var $new_var escape_uri src_str;

# 参数编码
var $new_var escape_args src_str;

# URI 组件编码
var $new_var escape_uri_component src_str;

# HTML 编码
var $new_var escape_html src_str;

# URI 解码
var $new_var unescape_uri src_str;

# Base64 编码
var $new_var base64_encode src_str;

# Base64url 编码
var $new_var base64url_encode src_str;

# Base64 解码
var $new_var base64_decode src_str;

# Base64url 解码
var $new_var base64url_decode src_str;


#### 加密哈希计算 ####
# CRC32
var $new_var crc32 src_str;

# MD5
var $new_var md5sum src_str;

# SHA1
var $new_var sha1sum src_str;

# SHA224
var $new_var sha224sum src_str;

# SHA256
var $new_var sha256sum src_str;

# SHA384
var $new_var sha384sum src_str;

# SHA512
var $new_var sha512sum src_str;

# HMAC_MD5 加密
var $new_var hmac_md5 src_str secret;

# HMAC_SHA1 加密
var $new_var hmac_sha1 src_str secret;

# HMAC_SHA224 加密
var $new_var hmac_sha224 src_str secret;

# HMAC_SHA256 加密
var $new_var hmac_sha256 src_str secret;

# HMAC_SHA384 加密
var $new_var hmac_sha384 src_str secret;

# HMAC_SHA512 加密
var $new_var hmac_sha512 src_str secret;

#### 时间范围判断 ####
# 确定当前时间是否满足给定的时间范围，至少需要一个参数。
# 如果满足所有条件，则返回 1，否则返回 0。
# 星期几用 0-6 表示，星期日为 0，时区格式为 gmt+0800
var $bool_var time_range [year=year_range] [month=month_range] [day=day_range] [wday=wday_range(0-6)] [hour=hour_range] [min=min_range] [sec=sec_range] [gmt | gmt+0000];


#### 时间格式 ####
# 将时间戳转换为 HTTP 时间（如果省略时间戳，则为当前时间）
var $new_var gmt_time [src_ts] http_time;

# 将时间戳转换为 Cookie 时间（如果省略时间戳，则为当前时间）
var $new_var gmt_time [src_ts] cookie_time;

# 将时间戳转换为指定格式的 GMT 时间（如果省略时间戳，则为当前时间）
var $new_var gmt_time [src_ts] date_format;

# 将时间戳转换为指定格式的本地时间（如果省略时间戳，则为当前时间）
var $new_var local_time [src_ts] date_format;

# 返回当前时间戳
var $new_var unix_time;

# 将 HTTP 时间转换为时间戳
var $new_var unix_time src_time http_time;

# 将指定日期转换为时间戳（如果全部省略则返回当前时间戳）
var $new_var unix_time src_time date_format [timezone];


#### IP ####
# 确定 IP 地址是否在 IP、CIDR 或 IPv4 范围内，如果是，则返回 1，否则返回 0
var $bool_var ip_range ip_str [ipv4 | ipv6 | cidr | ipv4_range ] ...;

# 根据 IP 地址和网络位计算网络地址
# 对于 IPv4：network_bits 范围为 1-32
# 对于 IPv6：network_bits 范围为 1-128
# 如果未指定 ipv6_network_bits，则使用与 ipv4_network_bits 相同的值
# 仅返回网络地址，不带前缀长度（例如，“10.0.0.0”而不是“10.0.0.0/8”）
var $new_var cidr ipv4/ipv6 ipv4_network_bits [ipv6_network_bits];

除正则表达式外，所有参数都可以包含变量。然而，参数值不正确将导致函数计算结果为空。

使用 var 指令定义的变量可以被 set 和 auth_request_set 等指令覆盖。

if 参数启用条件变量。如果条件评估为“0”或空字符串，则 var 不会被赋值。它将继续查找该变量的后续定义。

# 当请求头 A 存在时，变量的值为 'have-header-a'
var $new_var set have-header-a if=$http_a;

# 当请求头 A 不存在但请求头 B 存在时，变量的值为 'have-header-b'
var $new_var set have-header-b if=$http_b;

# 当请求头 A 和 B 都不存在时，变量的值为 'not-have-a-or-b'
var $new_var set not-have-a-or-b;

GitHub

您可以在 nginx-module-var 的 GitHub 仓库中找到有关此模块的其他配置提示和文档。