Nginx 常用内置变量详解
一、按功能分类
1. 请求相关变量（客户端信息）
| 变量 | 含义 | 示例值 | 常见用途 |
|---|
| $remote_addr | 客户端 IP 地址 | 192.168.1.100 | 日志记录、访问控制、限速 |
| $remote_port | 客户端端口 | 54321 | 调试、日志 |
| $remote_user | 认证用户名 | admin | 记录谁访问了系统 |
| $request_method | 请求方法 | GET / POST | 区分不同请求类型 |
| $host | 请求的域名 | www.example.com | 虚拟主机选择 |
| $http_user_agent | 用户浏览器信息 | Mozilla/5.0... | 统计分析、防爬虫 |
| $http_referer | 来源页面 | https://google.com | 防盗链、来源统计 |
2. URI 和参数相关
| 变量 | 含义 | 示例值 | 常见用途 |
|---|
| $uri | 不带参数的路径 | /api/user | 路由匹配、重写规则 |
| $document_uri | 同 $uri | /api/user | 同上 |
| $request_uri | 带参数的完整路径 | /api/user?id=123 | 原始请求记录 |
| $args | 请求参数 | id=123&name=test | 参数处理、日志 |
| $query_string | 同 $args | id=123&name=test | 同上 |
| $request_filename | 文件系统路径 | /var/www/html/index.php | 静态文件定位 |
3. 服务器相关
| 变量 | 含义 | 示例值 | 常见用途 |
|---|
| $server_addr | 服务器 IP | 10.0.0.1 | 多网卡时确定监听地址 |
| $server_name | 服务器名称 | localhost | 日志、调试 |
| $server_port | 服务器端口 | 80 | 多端口监听时区分 |
| $document_root | 网站根目录 | /usr/local/nginx/html | 文件路径组合 |
4. 其他特殊变量
| 变量 | 含义 | 常见用途 |
|---|
| $limit_rate | 限速值 | 动态控制下载速度 |
| $scheme | 协议 | http 或 https |
| $http_x_forwarded_for | 代理链中的客户端 IP | 获取真实客户端 IP |
| $time_local | 本地时间 | 日志记录 |
二、实际应用场景
场景1：日志格式定义
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for"';
access_log logs/access.log main;
场景2：IP 访问控制
location /admin/ {
if ($remote_addr !~ ^(192\.168\.1\.|10\.)) {
return 403 "禁止访问";
}
proxy_pass http://backend;
}
场景3：根据请求方法处理
location /api/ {
if ($request_method = 'OPTIONS') {
add_header Access-Control-Allow-Origin '*';
add_header Access-Control-Allow-Methods 'GET, POST, OPTIONS';
return 204;
}
proxy_pass http://backend;
}
场景4：限速控制
location /download/ {
set $limit_rate 100k; # 限速 100KB/s
alias /data/files/;
}
场景5：动态重定向
location /old/ {
rewrite ^/old/(.*)$ /new/$1 permanent;
}
场景6：防盗链
location /images/ {
valid_referers none blocked example.com *.example.com;
if ($invalid_referer) {
return 403;
}
root /data/images;
}
三、变量调试技巧
想查看变量具体值，可以用这个配置：
location /debug {
return 200 "
remote_addr: $remote_addr
remote_port: $remote_port
remote_user: $remote_user
request_method: $request_method
host: $host
uri: $uri
request_uri: $request_uri
args: $args
query_string: $query_string
server_addr: $server_addr
server_name: $server_name
server_port: $server_port
document_root: $document_root
request_filename: $request_filename
scheme: $scheme
http_user_agent: $http_user_agent
http_referer: $http_referer
";
}
访问 /debug 就能看到所有变量值。
四、变量使用注意事项
- $uri 和 $request_uri 的区别
$uri：经过重写后的路径，不带参数$request_uri：原始请求路径，带参数
- $args 和 $query_string：完全一样，可互换使用
- $document_uri：就是
$uri，历史遗留原因有两个名字
- 在 if 中使用变量
if ($request_method = POST) { ... }
if ($remote_addr ~* ^192\.168\.) { ... }
五、常用变量组合示例
# 记录完整请求信息
access_log logs/access.log combined;
log_format combined '$remote_addr - $remote_user [$time_local] '
'"$request_method $scheme://$host$request_uri" '
'$status $body_bytes_sent '
'"$http_referer" "$http_user_agent"';
# 获取真实客户端 IP（通过代理时）
set $real_ip $remote_addr;
if ($http_x_forwarded_for) {
set $real_ip $http_x_forwarded_for;
}
# 构建完整文件路径
set $full_path $document_root$uri;
六、速查表
| 类别 | 变量名 | 含义 |
|---|
| 客户端 | $remote_addr, $remote_port, $remote_user | 客户端 IP、端口、用户名 |
| 请求 | $request_method, $request_uri, $uri, $args | 方法、URI、参数 |
| 服务器 | $server_addr, $server_name, $server_port | 服务器 IP、名称、端口 |
| HTTP头 | $http_host, $http_user_agent, $http_referer | Host、UA、来源 |
| 路径 | $document_root, $request_filename | 根目录、文件路径 |
| 其他 | $limit_rate, $scheme, $time_local | 限速、协议、时间 |
发表回复