关于Nginx预设变量

Nginx 提供了许多预设变量（也叫内置变量），这些变量可以在配置文件中使用，用于动态处理请求、记录日志或条件判断等。它们通常以 $ 开头，表示当前请求的上下文信息。以下是一些常见的 Nginx 预设变量及其用途，分为几类列出：

1. HTTP 请求相关变量

这些变量与客户端发来的 HTTP 请求相关：

• $host：请求中的主机名（来自 Host 头），例如 demo.com 或 admin.demo.com。
• $http_host：与 $host 类似，但总是直接取自 Host 头，未经处理。
• $request：完整的请求行，例如 GET /index.html HTTP/1.1。
• $request_method：请求方法，例如 GET、POST。
• $request_uri：请求的完整 URI（包括查询字符串），例如 /path/to/page?query=1。
• $uri：请求的路径部分（不包括查询字符串），例如 /path/to/page。
• $query_string：查询字符串，例如 query=1。
• $args：与 $query_string 相同，表示查询参数。
• $scheme：请求的协议，例如 http 或 https。

2. 客户端信息相关变量

这些变量描述客户端的来源信息：

• $remote_addr：客户端的 IP 地址，例如 192.168.1.1。
• $remote_port：客户端的端口号。
• $remote_user：如果启用了认证（如 Basic Auth），这是客户端提供的用户名。
• $http_user_agent：客户端的 User-Agent 字符串，例如浏览器类型。
• $http_referer：请求的来源页面 URL（可能为空）。

3. 服务器相关变量

这些变量与 Nginx 服务器本身或匹配的配置相关：

• $server_addr：服务器的 IP 地址。
• $server_port：服务器监听的端口，例如 80 或 443。
• $server_name：当前匹配的 server 块中的 server_name，例如 demo.com。
• $server_protocol：请求的协议版本，例如 HTTP/1.1 或 HTTP/2.0。

4. 响应相关变量

这些变量与 Nginx 返回的响应相关：

• $status：响应状态码，例如 200、404。
• $body_bytes_sent：响应体的字节数（不包括头部）。
• $content_length：响应体的长度（来自 Content-Length 头）。
• $content_type：响应体的 MIME 类型（来自 Content-Type 头）。

5. 时间相关变量

这些变量提供请求处理的时间信息：

• $time_local：服务器本地时间，例如 27/Mar/2025:12:34:56 +0800。
• $time_iso8601：ISO 8601 格式的时间，例如 2025-03-27T12:34:56+08:00。
• $request_time：处理请求所花费的时间（单位：秒），从接收第一个字节开始计算。

6. 文件和路径相关变量

这些变量与文件系统或请求路径相关：

• $document_root：当前请求的根目录（由 root 指令定义）。
• $document_uri：与 $uri 相同，表示请求的路径。
• $realpath_root：root 指令的真实文件系统路径（解析符号链接后）。

7. 代理和上游相关变量

当 Nginx 用作反向代理时，这些变量很有用：

• $proxy_host：上游服务器的主机名。
• $upstream_addr：上游服务器的地址和端口，例如 10.0.0.1:8080。
• $upstream_status：上游服务器返回的状态码，例如 200。
• $upstream_response_time：上游服务器的响应时间（单位：秒）。

8. 其他常用变量

• $bytes_sent：发送给客户端的总字节数（包括头部和正文）。
• $connection：连接的序列号。
• $connection_requests：当前连接上处理的请求数。
• $limit_rate：当前请求的限速值（如果设置了限速）。
• $nginx_version：Nginx 的版本号，例如 1.18.0。

使用示例

以下是一个简单的 Nginx 配置，展示如何使用预设变量：

server {
    listen 80;
    server_name demo.com;

    location / {
        # 记录访问日志，包含客户端 IP、请求方法和 URI
        access_log /var/log/nginx/access.log combined;
        # 如果是 admin.demo.com，重定向到 demo.com
        if ($host = "admin.demo.com") {
            return 301 http://demo.com$request_uri;
        }
        root /var/www/demo;
        try_files $uri $uri/ /index.html;
    }
}

• $host 用于判断请求的域名。
• $request_uri 用于保留原始请求路径。

自定义日志格式示例：

log_format custom '$remote_addr - $request_method $uri - $status';
access_log /var/log/nginx/custom.log custom;