Nginx内置变量详解

原创已于 2025-11-22 22:15:06 修改 · 974 阅读

12 ·

CC 4.0 BY-SA版权

文章标签：

#nginx #运维

于 2025-11-22 21:27:12 首次发布

Nginx 的内置变量是其配置灵活性的核心，它们提供了丰富的客户端请求和服务器状态信息。下述表格汇总了这些变量，并附带了实用的分类和说明，方便快速查阅和使用。

1. Nginx 内置变量速查表

变量类别	变量名	说明与示例
请求URI与参数	`$uri`/ `$document_uri`	当前请求的URI（不含参数），可能经过内部重写。例：`/api/user`
	`$request_uri`	客户端原始的完整请求URI（含参数）。例：`/api/user?id=1`
	`$args`/ `$query_string`	请求行中的参数字符串。例：`id=1&name=test`
	`$arg_name`	获取指定名称的参数值。例：`$arg_id`的值为 `1`
	`$is_args`	如果请求有参数，值为`?`，否则为空。常用于拼接URL
客户端信息	`$remote_addr`	客户端的直接IP地址
	`$http_x_forwarded_for`	透传客户端原始IP的请求头，常用于识别经过代理的真实用户IP
	`$http_user_agent`	客户端浏览器标识
	`$http_referer`	请求来源页面
请求内容	`$request_method`	HTTP 请求方法，如 `GET`或 `POST`
	`$content_length`	请求头中的 `Content-Length`字段
	`$content_type`	请求头中的 `Content-Type`字段
	`$request_body`	客户端的请求主体内容
服务器信息	`$host`	请求的主机名，优先级：请求行 > "Host"请求头 > 匹配的服务器名
	`$server_name`	当前匹配的服务器块名称
	`$server_port`	请求到达的服务器端口
	`$scheme`	请求协议，`http`或 `https`
	`$https`	若为SSL安全模式，值为 `on`，否则为空
文件路径	`$document_root`	当前请求的文档根目录或别名
	`$request_filename`	当前请求映射到的本地文件系统路径
响应与性能	`$status`	HTTP 响应状态码
	`$body_bytes_sent`	发送给客户端的响应体字节数（不含头）
	`$request_time`	处理请求所耗费的时间
其他常用变量	`$cookie_name`	获取指定名称的 Cookie 值
	`$http_name`	获取任意请求头字段，将`-`替换为下划线，字母小写。例：`$http_accept_language`
	`$nginx_version`	Nginx 版本号
	`$time_iso8601`	服务器时间的 ISO 8601 格式

2. 核心变量详解与应用场景

了解这些变量的典型用法，能帮助你更好地配置Nginx。

精确控制：$uri 与 $request_uri
- $uri反映的是当前请求经过Nginx内部处理（如重写规则）后的URI，不带参数。它常用于内部重定向或作为其他指令的输入。
- $request_uri则是客户端发来的原始请求，包含所有参数，且是只读的。在构建反向代理请求时，如果你希望原封不动地将客户端请求传递给后端，通常会使用 $request_uri。
获取客户端真实IP：$remote_addr 与 $http_x_forwarded_for
- 当客户端与Nginx服务器之间没有代理时，$remote_addr就是客户端的真实IP。
- 当存在反向代理（如CDN、负载均衡器）时，$remote_addr会是最后一个代理服务器的IP。此时，代理服务器通常会将客户端的原始IP放在 X-Forwarded-For请求头中，这个值可以通过 $http_x_forwarded_for变量获取。处理多级代理时，这个变量可能包含一个IP列表。
灵活获取请求头：$http_name

这是一个通用变量，name可以替换为任何请求头字段名的小写字母和下划线形式。例如，获取 Accept-Language头，使用 $http_accept_language。这为根据请求头信息做差异化处理提供了极大灵活性。

3. 实际应用举例

下面通过几个常见场景展示这些变量的用法。

记录详细日志

你可以在 log_format中组合使用变量，记录更丰富的信息。例如，记录客户端IP、用户代理、请求处理时间和响应状态：

log_format main '$remote_addr - $remote_user [$time_local] '
               '"$request" $status $body_bytes_sent '
               '"$http_referer" "$http_user_agent" '
               '$request_time';

访问控制与重定向

根据参数重写URL：

if ($arg_version = "v2") {
    rewrite ^/api/(.*)$ /v2/api/$1 last;
}

基于原始IP进行访问限制（注意：需确保代理服务器正确设置了 X-Forwarded-For）：

# 允许来自192.168.1.100和10.0.0.0/8网段的请求
if ($http_x_forwarded_for !~* "^(192\.168\.1\.100|10\..*)") {
    return 403;
}

代理配置

在反向代理设置中，常使用变量向后端传递原始请求信息：

location /api/ {
    proxy_pass http://backend_server;
    # 将原始Host头传递给后端
    proxy_set_header Host $host;
    # 传递客户端真实IP
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

4. 注意事项

变量使用场景：并非所有变量都可以在所有配置指令中使用，具体需参考Nginx官方文档。
条件判断：在Nginx配置中，尤其是在 if指令中使用变量进行字符串匹配或条件判断时，需要特别注意Nginx的匹配规则，有时可能需要使用 ~*（不区分大小写匹配）或 ~（区分大小写匹配）等操作符。
变量性能：大部分内置变量开销很小，但频繁在复杂逻辑或高并发场景下使用某些涉及字符串处理的变量仍需注意。