在 Nginx 配置中,变量是核心组件之一,用于存储数据、控制逻辑流程(如 if 判断)、日志记录以及动态构建响应。Nginx 的变量主要分为两大类:内置变量和自定义变量。

以下是关于这两类变量的详细解析。

内容总览

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";

通过合理组合内置变量和自定义变量,可以实现灵活的访问控制、重写规则、负载均衡策略以及详细的日志记录。