lolly/docs/25-nginx-variables-reference.md

Nginx 内置变量速查表

本文档汇总 nginx 所有模块提供的内置变量，便于快速查阅。

---

1. HTTP 核心模块变量 (ngx_http_core_module)

请求信息

变量	说明	示例值
$arg_name	请求参数 name 的值	foo
$args	所有请求参数	a=1&b=2
$is_args	是否有参数	? 或 空
$query_string	同 $args	a=1&b=2
$content_length	Content-Length 头	1024
$content_type	Content-Type 头	application/json
$cookie_name	Cookie name 的值	session_id

客户端信息

变量	说明	示例值
$remote_addr	客户端 IP	192.168.1.1
$remote_port	客户端端口	54321
$binary_remote_addr	二进制 IP（4/16字节）	用于 limit_conn
$remote_user	认证用户名	admin

URI 相关

变量	说明	示例值
$uri	当前请求 URI（解码后）	/path/to/file
$document_uri	同 $uri	/path/to/file
$request_uri	原始请求 URI（含参数）	/path?a=1
$host	请求主机名（优先 Host 头）	example.com
$hostname	服务器主机名	server01
$server_name	server 配置的第一个名字	example.com

请求详情

变量	说明	示例值
$request	完整请求行	GET / HTTP/1.1
$request_method	请求方法	GET/POST
$request_body	请求体内容	{...}
$request_body_file	请求体临时文件路径	/tmp/...
$request_completion	请求完成状态	OK 或 空
$request_filename	映射的文件路径	/var/www/index.html
$request_id	唯一请求 ID（1.11.0+）	abc123...
$request_length	请求长度（含头）	2048
$request_time	请求处理时间（秒）	0.001
$document_root	root 指令值	/var/www
$realpath_root	root 的真实路径	/var/www

服务器信息

变量	说明	示例值
$server_addr	服务器 IP	10.0.0.1
$server_port	服务器端口	80
$scheme	协议	http/https
$server_protocol	HTTP 版本	HTTP/1.1
$https	是否 HTTPS	on 或 空

响应信息

变量	说明	示例值
$status	响应状态码	200/404
$body_bytes_sent	响应体字节数	1024
$bytes_sent	总发送字节	2048

时间相关

变量	说明	示例值
$time_local	本地时间	03/Apr/2026:14:30:00
$time_iso8601	ISO8601 时间	2026-04-03T14:30:00
$msec	毫秒时间戳	1617456789.123

连接信息

变量	说明	示例值
$connection	连接序号	12345
$connection_requests	连接请求数	10
$pipe	是否管道化	p 或 .
$pid	worker 进程 PID	12345

PROXY 协议

变量	说明
$proxy_protocol_addr	客户端真实 IP
$proxy_protocol_port	客户端真实端口
$proxy_protocol_server_addr	服务器 IP
$proxy_protocol_server_port	服务器端口

TCP 信息

变量	说明
$tcpinfo_rtt	RTT（微秒）
$tcpinfo_rttvar	RTT 方差
$tcpinfo_snd_cwnd	发送窗口
$tcpinfo_rcv_space	接收窗口

---

2. Upstream 模块变量 (ngx_http_upstream_module)

变量	说明	用途
$upstream_addr	后端地址	日志
$upstream_status	后端状态码	监控
$upstream_response_time	后端响应时间	性能分析
$upstream_response_length	后端响应长度	日志
$upstream_connect_time	连接耗时	性能分析
$upstream_header_time	头部接收耗时	性能分析
$upstream_first_byte_time	首字节时间	性能分析
$upstream_bytes_sent	发送到后端字节	流量统计
$upstream_bytes_received	从后端接收字节	流量统计
$upstream_cache_status	缓存状态	HIT/MISS/BYPASS
$upstream_http_name	后端响应头	提取认证信息
$upstream_cookie_name	后端 Cookie	提取 Cookie

---

3. SSL/TLS 模块变量 (ngx_http_ssl_module)

变量	说明
$ssl_cipher	加密套件
$ssl_ciphers	支持的加密套件列表
$ssl_protocol	SSL 协议版本
$ssl_server_name	SNI 服务器名
$ssl_session_id	会话 ID
$ssl_session_reused	是否重用会话
$ssl_client_cert	客户端证书
$ssl_client_raw_cert	客户端原始证书
$ssl_client_escaped_cert	转义证书
$ssl_client_fingerprint	证书指纹
$ssl_client_i_dn	签发者 DN
$ssl_client_s_dn	主体 DN
$ssl_client_serial	证书序列号
$ssl_client_verify	验证结果
$ssl_client_v_start	证书开始时间
$ssl_client_v_end	证书结束时间
$ssl_client_v_remain	证书剩余天数
$ssl_curves	支持的曲线
$ssl_early_data	是否早期数据

---

4. Proxy 模块变量 (ngx_http_proxy_module)

变量	说明
$proxy_add_x_forwarded_for	X-Forwarded-For 链
$proxy_host	proxy_pass 主机
$proxy_port	proxy_pass 端口

---

5. FastCGI 模块变量

变量	说明
$fastcgi_path_info	PATH_INFO
$fastcgi_script_name	SCRIPT_NAME

---

6. Stream 模块变量 (ngx_stream_core_module)

变量	说明
$binary_remote_addr	二进制 IP
$connection	连接序号
$remote_addr	客户端 IP
$remote_port	客户端端口
$server_addr	服务器 IP
$server_port	服务器端口
$status	状态码
$time_iso8601	ISO 时间
$time_local	本地时间
$upstream_addr	后端地址
$upstream_bytes_sent	发送字节
$upstream_bytes_received	接收字节
$upstream_connect_time	连接时间

---

7. SSL Preread 模块变量 (ngx_stream_ssl_preread_module)

变量	说明
$ssl_preread_protocol	SSL 协议版本
$ssl_preread_server_name	SNI 名称

---

8. Geo 模块变量 (ngx_http_geo_module)

变量	说明
自定义	根据 IP 映射的值

---

9. Map 模块变量 (ngx_http_map_module)

变量	说明
自定义	映射规则生成的值

---

10. Limit Request 模块变量

变量	说明
$limit_req	限流延迟时间（毫秒）

---

11. 常用组合示例

日志格式

log_format main '$remote_addr - $remote_user [$time_local] '
                '"$request" $status $body_bytes_sent '
                '"$http_referer" "$http_user_agent" '
                'rt=$request_time uct="$upstream_connect_time" '
                'uht="$upstream_header_time" urt="$upstream_response_time"';

性能监控

log_format perf '$request_id $request_time $upstream_response_time '
                '$upstream_connect_time $upstream_header_time';

安全日志

log_format security '$remote_addr $request_method $request_uri '
                    '$status $ssl_protocol $ssl_cipher';

---

文档生成时间：2026-04-03 基于 nginx 1.24+ 版本