【Nginx15】Nginx学习：HTTP核心模块（十二）内嵌变量

Nginx学习：HTTP核心模块（十二）内嵌变量

关于内嵌变量，其实就是 Nginx 开放给我们的在配置文件中可以使用的变量。源码中无非就是替换成真实的代码变量进行操作。这些变量可以帮助我们做很多事情。之前的文章中其实也有不少地方用到了，比如说 $uri 这个变量，是不是已经见过很多次了。而且这些变量基本上和 Apache 是对应的。

默认提供的变量非常多，在这里我也只是将官网的 HTTP 核心模块中提供的这些变量先列出来，然后尽已所能的借助工具翻译一下。最常用的那些大家至少要知道是什么意思，而不常用的那些也可以随时过来查阅。大部分自己使用 return 指令打印一下返回的结果看下效果就好了，特殊的我会单独写出来并加粗字体或者直接放上测试效果代码。

• $arg_[name] 请求行中的 name 参数，注意这个 name 是可变的，指的就是 GET 参数。

// nginx.conf
location /params1/ {
 return 200 $arg_a;
}

// linux
[root@localhost ~]# curl http://localhost/params1/?a=111
111

看出来效果了吧，直接可以获得我们的 GET 参数中的某一个具体的参数。如果要获取全部的参数，就要使用下面的变量。

• $args 请求行中参数字符串。

// nginx.conf
location /params2/ {
 return 200 $args;
}

// linux
[root@localhost ~]# curl "http://localhost/params2/?a=111&b=222"
a=111&b=222

• $binary_remote_addr 客户端IP地址的二进制形式，值的长度总是4字节的 IPv4 或者16字节的 IPv6 地址。

• $body_bytes_sent Nginx 返回给客户端的字节数，不含响应头。

• $bytes_sent nginx返回给客户端的字节数。

• $connection 连接的序列号。这个连接是 Nginx 自己计数的，比如刚开机或者完全重启 Nginx 就会从 1 开始，然后快速访问重用 TCP 连接时也不会增加，大家可以自己试下哦。

• $connection_requests 当前通过连接发出的请求数。啥意思呢？也是和连接有关的，指的是当前这个 TCP 连接下的请求数，如果是新开的一个 TCP 连接，就会归零从1开始。用 CURL 和浏览器分别测试就很明显。浏览器请求一次后等一会再试也可以看到效果，和之前我们讲过的连接及长连接的内容吻合。

• $connection_time 连接时间（以秒为单位，分辨率为毫秒）。当前建立的 TCP 连接的持续连接时间。同样的，新开 TCP 连接之后归零，和上面的测试方式类似。

• $content_length “Content-Length” 请求头的值。

• $content_type “Content-Type” 请求头的值。

• $cookie_[name] 和第一个 $arg_[name] 一样的，这里是获取指定的 Cookie 的值。

• $document_root 当前请求的 root 或者 alias 指令确定的目录路径。如果是相对路径，比如 root html 那个，返回的也是完整的绝对路径。

• $document_uri 和 $uri 是一样的，之前我们就用过了，一会去那边看。

• $host “Host” 请求头的值，如果没有该请求头，则为与请求对应的虚拟主机的首要主机名。

• $hostname 机器名称。

• $http_[name] 任意请求头的值；变量名的后半部为转化为小写并且用下划线替代横线后的请求头名称。还是和 $arg_[name] 一样，只不过这回是请求头中指定的字段值。

• $https 如果连接是SSL模块，返回 on ，否则返回空字符串。

• $is_args 如果请求行带有参数，返回 “?” ，否则返回空字符串。也就是说，有 GET 参数的话，这个变量的值就是个问号，如果没有 GET 参数的话，它就是空的。

• $limit_rate 允许设置此值来限制连接的传输速率。之前在学习限流相关内容的时候我们已经了解过啦。

• $msec 当前时间戳，单位是秒，精度是毫秒。(1.3.9, 1.2.6)

• $nginx_version Nginx 的版本号。

• $pid worker进程的PID，如果你当前只有一个 worker 进程，那么可以修改下 worker_process 多设置几个就能看出效果了。

• $pipe 如果当前请求使用 pipeline 了，就会设置为 p ，否则的话就是 . 。这个 pipeline 也是 HTTP1.1 的一个特性，我也只是知道皮毛，这里就不多解释了，大家可以自己查阅下相关的资料。

• $proxy_protocol_addr 通过代理协议获取真实地址。这个和 HAProxy 这种四层代理服务器有关，不在我们的讨论范围内。简单来说，就是四层负载转发过来的请求，要拿到真实 IP 比较麻烦，不像 Nginx 做反向代理时可以直接设置头。但如果使用 HAProxy 抛出的 Proxy Protocol 的话，就会简单很多。这一块的内容我记下了，如果将来要学习 HAProxy 相关的内容的话，那么会再进行更详细的测试与解读。

• $proxy_protocol_port 和上面的一样，不过是获取端口号。

• $proxy_protocol_server_addr 通过代理协议获取服务器地址。

• $proxy_protocol_server_port 通过代理协议，获取服务器端口号。

• $query_string 和 $args 一样。

• $realpath_root 按 root 或者 alias 配置算出的当前请求的绝对路径，如果有软连接的文件也会解析成真实的文件路径。这个比较常用，我这里就是默认的 /usr/local/nginx/html 这个目录。

• $remote_addr 客户端的 IP 地址。非常重要的，做反向代理的时候转发真实 IP 地址就靠它了。

• $remote_port 客户端的端口号。注意，是客户端的，不是我们在 Nginx 用 listen 监听的。

• $remote_user 为基本用户认证提供的用户名。这个直接请求加个 Authorization 请求头就可以测试出来，之前我们学习过 PHP的HTTP验证https://mp.weixin.qq.com/s/H8I1MSeqsuOn16lKXZ4Nrw ，其实，HTTP相关的验证直接在 Nginx 配就可以，后面我们也会学习到。

• $request 完整的原始请求行。HTTP 请求中的第一行哦。

• $request_body 请求正文。只有通过 proxy_pass 或者 fastcgi_pass 相关配置路径的路径中，这个变量里面才有值。最常见的一个需求，将 POST 请求的参数也放到 access 日志中，就需要使用这个变量。注意，只有动态页面才可以使用，因此才必须是需要 proxy_pass 或者 FastCGI 这些的路径。

• $request_body_file 请求正文的临时文件名。处理完成时，临时文件被删除。这个和我们之前讲过的 client_body_in_file_only 参数有关。如果在被代理的请求或者 FastCGI 中传递临时文件名，就应该禁止传递请求正文。使用 proxy_pass_request_body off 配置和 fastcgi_pass_request_body off 配置来禁止传递普通的请求正文。

• $request_completion 请求完成时返回 ok ，否则返回空字符串。没测试出效果，有了解的小伙伴可以留言哦。

• $request_filename 比较有用的一个变量，根据 root 或者 alias 配置的路径，以及请求的 URI ，得到当前请求的完全文件路径。

• $request_id 生成一个 16 字节的唯一哈希 ID ，在 1.11.0 版本之后才有的。

• $request_length 请求的长度，包括请求行、请求头以及请求体的长度。

• $request_method 请求方法，就是 POST 、GET 那些啦，比较有用的。

• $request_time 请求处理的时间，单位为秒，精度是毫秒(1.3.9, 1.2.6)，请求处理时间从由客户端接收到第一个字节开始计算。

• $request_uri 返回原始的请求行（带 GET 参数的），注意它和 $uri 以及 $document_uri 的区别。

• $scheme 请求协议的类型，比如 http 或 https 。

• $sent_http_[name] 响应头的信息，这个 name 可以替换成响应头的名称，比如说 $sent_http_connection 就是响应头里面的 Connection 内容。

• $sent_trailer_[name] 响应结束时发送的任意字段(1.13.2)，变量名的后半部分 name 可以替换成任意响应头的名称。这个不太好测，需要使用日志，我们可以先在 http 模块中定义一个自定义日志 log_format vvv op_trailer=$sent_trailer_op; 这一块的内容我们后面才会学到。然后在 location 中添加 add_trailer op 111; 以及 access_log logs/params2.log vvv; 。接着访问链接之后，就可以在 /usr/local/nginx/logs 下面的 params2.log 日志文件中看到我们设置的内容。

• $server_addr 接受请求的服务器地址。为计算这个值，通常需要进行一次系统调用。为了避免系统调用，必须指定listen 指令的地址，并且使用 bind 参数。我这里啥都没配，就是显示当前服务器的 IP 地址。

• $server_name 接受请求的虚拟主机的首要主机名。server_name 配置指令的第一个主机名。

• $server_port 接受请求的虚拟主机的端口。

• $server_protocol 请求协议，通常为“HTTP/1.0”或“HTTP/1.1”。

• $status 返回响应的状态码。

• $tcpinfo_rtt, $tcpinfo_rttvar, $tcpinfo_snd_cwnd, $tcpinfo_rcv_space 客户端TCP连接的信息，在支持套接字选项TCP_INFO的系统中可用。

• $time_iso8601 ISO 8601 标准的服务器当前时间，我这里的结果是 2022-08-14T22:43:00-04:00 。

• $time_local 日志中的时间记录变量，格式是 14/Aug/2022:22:43:00 -0400 。

• $uri 非常常用的，返回完整的 URI ，不包含 GET 参数。它值可能随请求的处理过程而改变。 比如，当进行内部跳转时，或者使用默认页文件。

总结

哈哈哈哈，是不是好简单啊，水了一篇文章。不过虽说内容少，但咱们可是一个一个真实地测了一下效果的，真不是从哪里复制粘贴来就完事了。

好了，这回真的要和 HTTP 核心模块道别了，我们即将进入 HTTP 扩展模块的学习了。说是扩展，但是其实也都是随安装包一起发布的，只需要在编译安装时的 configure 添加相应的模块即可，这一类的教程太多了，熟悉 Linux 安装软件的同学也都不会有问题。另外也有一部分模块本身就包含在核心源码中，只是区分出了不同的模块分类。因此，咱们还是以配置指令的介绍学习为主，商业版部分的模块也不在我们的学习范围内。

参考文档：

http://nginx.org/en/docs/http/ngx_http_core_module.html