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.3，于 2026 年 4 月 02 日发布。

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 仓库中找到此模块的其他配置提示和文档。