nginx变量使用

Nginx 变量用于在配置中引用动态值，下面梳理常用内置变量和自定义变量的用法。

内置变量

请求信息

变量	说明
`$uri`	当前请求 URI（不含参数）
`$request_uri`	完整 URI（含参数）
`$request_method`	请求方法（GET/POST）
`$query_string`	请求参数
`$args`	同 `$query_string`
`$request`	完整请求行

客户端信息

变量	说明
`$remote_addr`	客户端 IP 地址
`$remote_port`	客户端端口
`$http_user_agent`	浏览器标识
`$http_referer`	来源页面
`$http_cookie`	Cookie 信息

服务器信息

变量	说明
`$server_name`	服务器名
`$server_addr`	服务器 IP
`$server_port`	服务器端口
`$host`	请求 Host 头
`$scheme`	协议（http/https）

响应信息

变量	说明
`$status`	响应状态码
`$body_bytes_sent`	响应体字节数
`$bytes_sent`	总发送字节数
`$request_time`	请求处理时间（秒）
`$upstream_response_time`	后端响应时间

文件路径

变量	说明
`$document_root`	当前请求的 root 路径
`$fastcgi_script_name`	FastCGI 脚本路径

自定义变量

set 指令

nginx

server {
    set $my_root /var/www/mysite;
    root $my_root;
}

条件赋值

nginx

set $custom_log 0;
if ($request_uri ~ "/admin/") {
    set $custom_log 1;
}

map 指令

按条件映射变量值：

nginx

http {
    map $http_user_agent $is_mobile {
        ~Mobile  1;
        default  0;
    }
}

按状态码分类日志

nginx

map $status $log_type {
    ~^[23]  normal;
    ~^4     client_error;
    ~^5     server_error;
    default unknown;
}

请求方法映射

nginx

map $request_method $cache_time {
    GET  30m;
    HEAD 30m;
    default 0;
}

geo 指令

基于 IP 地址映射变量：

nginx

geo $geo_country {
    default     ZZ;
    192.168.1.0/24  CN;
    10.0.0.0/8      US;
}

变量使用场景

日志格式

nginx

log_format custom '$remote_addr - [$time_local] "$request" $status '
                  '$request_time "$http_referer"';

重定向

nginx

return 301 https://$host$request_uri;

代理头

nginx

proxy_set_header Host $host;
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;

条件判断

nginx

if ($http_user_agent ~* "bot") {
    return 403;
}

注意事项
变量名区分大小写，如 $uri ≠ $URI
Nginx 变量是延迟求值，使用时才计算
if 指令在 location 块内使用有限制（仅 rewrite、return、error_page 安全）
map 指令必须在 http 段定义，不能在 server 段使用
$arg_name 可获取指定参数值，如 $arg_token

获取请求参数

nginx

# 获取 ?id=123 中的 id 值
set $item_id $arg_id;

# 获取 ?page=1 中的 page 值
set $page_num $arg_page;

要点总结

Nginx 内置变量涵盖请求、客户端、服务器、响应、文件路径等类别
set 指令自定义变量，map 指令按条件映射变量值
geo 指令基于 IP 地址映射变量
变量延迟求值，使用时才计算
if 指令在 location 块内使用受限，仅 rewrite/return/error_page 安全
map 指令需在 http 段定义，不能在 server 段使用

📝 发现内容有误？点击此处直接编辑