Nginx 中如何使用 if 语句根据条件控制 access

nginx 中不能在 if 块内直接开关 access_log，但可通过 map 指令预定义日志开关（推荐）或设 access_log 路径为空实现按需记录；map 必须定义在 http 块中，配合 access_log ... if=$var 使用，变量非空且非 0 时才写入日志。

nginx 中如何使用 if 语句根据条件控制 access_log 记录

Nginx 中不能在 if 块内直接开启或关闭 access_log，因为 access_log 指令不支持在条件块中动态启用/禁用。但可以通过“日志路径为空”或“使用 map 指令预判条件”这两种可靠方式实现按需记录 access log。

用 map 预定义日志开关（推荐）

map 是 Nginx 官方推荐的条件映射机制，性能好、语法清晰，且可在 http 块中定义，供 access_log 引用。

例如：只对非健康检查请求记录日志（过滤掉 /healthz）：

http {
    map $request_uri $loggable {
        default 1;
        ~^/healthz 0;
    }
<pre class="brush:php;toolbar:false;">server {
    access_log /var/log/nginx/access.log combined if=$loggable;
    # 其他配置...
}

}

说明：

Nginx

在宝塔面板中轻松管理Nginx高性能Web服务器。提供可视化配置反向代理、负载均衡、SSL证书及HTTP缓存功能，一键优化高并发性能，助您高效搭建稳定、快速的网站运行环境。

下载

map 必须定义在 http 块内，不能在 server 或 location 中
access_log ... if=$loggable 中的 if= 表示：仅当变量值为非空且非 0 时才写入日志
支持正则匹配（如 ~^/api/）、字符串精确匹配、IP 判断（结合 $remote_addr）等

用空路径禁用日志（兼容旧版本）

对于不支持 if= 参数的旧版 Nginx（

http {
    map $request_uri $log_path {
        default "/var/log/nginx/access.log";
        ~^/status  "";
        ~^/ping    "";
    }
<pre class="brush:php;toolbar:false;">server {
    access_log $log_path combined;
    # ...
}

}

注意：

空字符串 "" 会让 Nginx 忽略该条 access_log 指令，不报错也不写日志
需确保 map 变量始终有默认值，避免未匹配时变量为空导致意外行为
此方式不如 if= 语义明确，但兼容性更好

不推荐的做法：避免在 if 中写 access_log

以下写法是错误的，Nginx 会拒绝加载配置：

server {
    location / {
        if ($request_uri ~ ^/debug) {
            access_log /var/log/nginx/debug.log;  # ❌ 语法错误！
        }
        # ...
    }
}

原因：

access_log 是“上下文敏感指令”，只允许出现在 http、server、location 块顶层，不能嵌套在 if、limit_except 等块中
即使语法侥幸通过，行为也不确定，可能被忽略或引发段错误

常见实用场景举例

结合 map 可轻松实现多种过滤逻辑：

屏蔽特定 User-Agent（如爬虫）：map $http_user_agent $loggable { ~*bot 0; default 1; }
仅记录 4xx/5xx 错误请求：map $status $log_error { ~^[45] 1; default 0; }，再配 access_log ... if=$log_error
按客户端 IP 白名单记录：map $remote_addr $log_ip { 192.168.1.100 1; default 0; }