在 Nginx 配置中,变量是核心组件之一,用于存储数据、控制逻辑流程(如 if 判断)、日志记录以及动态构建响应。Nginx 的变量主要分为两大类:内置变量和自定义变量。
以下是关于这两类变量的详细解析。
内容总览
一、内置变量 (Built-in Variables)
内置变量由 Nginx 各个模块预先定义,用户可以直接在配置文件中使用,无需声明。它们通常以 $ 开头,反映了当前请求、服务器状态或客户端信息。
1. 常见内置变量分类
请求行与 URI 相关
$request_uri:包含请求参数的完整原始 URI(例如/index.php?id=1)。$uri/$document_uri:当前请求的 URI,不包含查询参数(例如/index.php经过规范化处理后的值)。$args/$query_string:URL 中的查询字符串部分(例如id=1&name=test)。$is_args:如果请求包含查询参数,值为?,否则为空字符串。常用于拼接 URL。$request_method:客户端使用的 HTTP 方法(GET, POST, PUT 等)。
客户端信息相关
$remote_addr:客户端的 IP 地址。$remote_port:客户端发起请求的端口。$http_user_agent:客户端浏览器的 User-Agent 信息。$http_cookie:客户端发送的所有 Cookie 信息。$cookie_<name>:获取特定名称的 Cookie 值(例如$cookie_sessionid)。
服务器与连接相关
$host:请求头中的 Host 字段值。如果请求头中没有 Host,则使用匹配到的 server_name。$server_addr:服务器接收请求的 IP 地址。$server_port:服务器接收请求的端口。$server_name:匹配当前请求的 server 块中的 server_name 指令值。$scheme:请求使用的协议(http 或 https)。
代理与转发相关
$proxy_add_x_forwarded_for:在反向代理场景中常用。它的值是客户端请求头中的 X-Forwarded-For 字段内容(如果有),后跟逗号和$remote_addr。如果请求头中没有该字段,则等于$remote_addr。这有助于在后端服务器获取真实的客户端 IP。
其他动态变量
$arg_<name>:获取 URL 查询参数中指定名称的值。例如,对于请求/?word=dog,$arg_word的值为dog。这是动态内置变量,变量名取决于请求参数。
2. 内置变量的特性
- 只读性:大多数内置变量是只读的,不能通过 set 指令修改(例如
$remote_addr,$arg_xxx)。尝试修改不可变变量会导致 Nginx 报错。 - 动态计算:部分变量(如
$args,$arg_xxx)是动态生成的,每次请求时根据实际输入确定。 - 前缀规则:Nginx 使用前缀来识别动态内置变量,如
arg_(查询参数)、http_(请求头)、sent_http_(响应头)、cookie_(Cookie)。
二、自定义变量 (Custom Variables)
自定义变量由用户在配置文件中显式定义,主要用于存储中间结果、标记状态或构建复杂的字符串。
1. 定义方式
主要使用 set 指令(属于 ngx_http_rewrite_module 模块)进行定义和赋值。
location /example {
set $my_var "hello";
set $combined "$my_var world";
return 200 $combined;
}
2. 命名规则
- 前缀:必须以
$符号开头。 - 有效字符:变量名只能包含字母(a-z, A-Z)、数字(0-9)和下划线(_)。
- 花括号用法:当变量名需要与相邻字符区分时,必须使用
${}包裹变量名。 - 示例:若想输出变量
$a的值后紧跟字符s,应写为${a}s。如果写成$as,Nginx 会将其解析为名为as的变量,而非变量a加字符s。
3. 变量插入与拼接
Nginx 支持将变量直接嵌入字符串中,且对插入数量没有限制。
- 简单拼接:
set $full_url "$scheme://$host$request_uri"; - 复杂场景:在处理动态内容时,利用
${}可以清晰界定变量边界,避免歧义。
4. 其他定义方式
除了 set 指令,某些模块也会隐式创建自定义变量。
geo 模块
可以根据客户端 IP 定义变量。
geo $country {
default ZZ;
127.0.0.1 US;
}
map 模块
根据一个变量的值映射到另一个变量。
map $http_user_agent $mobile {
default 0;
~Mobile 1;
}
三、内置变量与自定义变量的对比
| 特性 | 内置变量 (Built-in) | 自定义变量 (Custom) |
|---|---|---|
| 来源 | Nginx 内核或模块预定义 | 用户通过 set, geo, map 等指令定义 |
| 声明需求 | 无需声明,直接使用 | 需先定义(赋值即定义) |
| 可写性 | 大部分只读,少数可写 | 可读写 |
| 数据类型 | 绝大多数为字符串类型 | 字符串类型 |
| 典型用途 | 获取请求信息、日志记录、条件判断 | 逻辑标记、URL 重构、中间值存储 |
| 性能影响 | 静态内置变量开销极小;动态变量需实时计算 | 每次请求处理时可能涉及计算或内存分配 |
四、使用注意事项
- 变量作用域:Nginx 变量没有传统编程语言中的局部/全局严格作用域概念,但它们的值是与请求(Request)绑定的。每个请求都有自己独立的变量值副本。
- 空值处理:如果引用的变量不存在或值为空,Nginx 通常会用空字符串代替。例如,访问
/?word=book时,若引用$arg_words(注意多了一个 s),由于参数中只有 word,Nginx 找不到 words 参数,因此$arg_words为空。 - 性能考量:
- 频繁使用复杂的变量拼接或正则捕获可能会轻微增加 CPU 开销。
- 某些变量(如
$request_body)如果需要读取请求体,可能会导致 Nginx 缓冲整个请求体到内存或临时文件,影响性能。 - 调试技巧:在排查问题时,可以通过
return指令或access_log打印关键变量的值,以确认其是否符合预期。例如:return 200 "IP: $remote_addr, URI: $request_uri";
通过合理组合内置变量和自定义变量,可以实现灵活的访问控制、重写规则、负载均衡策略以及详细的日志记录。