Nginx 如何在 Nginx 中使用 log_format 结合 JSON 结构化输出日志

Nginx中配置JSON日志需在http块用单引号定义log_format，键和字符串值均用双引号，变量直接插入；应用时指定access_log路径与格式名；对含特殊字符的变量（如$http_user_agent）应配合map预处理；最后用python3 -m json.tool校验合法性。

在 Nginx 中使用 log_format 输出 JSON 格式日志，核心是定义一个包含变量的 JSON 字符串格式，并确保特殊字符（如双引号、空格）被正确转义或引用。Nginx 本身不解析 JSON，只是拼接字符串，所以关键在于格式合法、可被下游日志系统（如 Filebeat、Loki、ELK）直接消费。

定义 JSON 格式的 log_format

在 http 块中定义 log_format，用单引号包裹整个格式字符串，避免 shell 或配置解析干扰；JSON 内部字段名和字符串值都用双引号，变量（如 $time_local）直接插入：

1. 必须用单引号包围整个 log_format 值，否则 Nginx 会把空格或花括号误判为语法分隔符
2. 所有 JSON 键和静态字符串值都要用双引号，例如 "status": "$status"
3. 变量值若含双引号、换行或控制字符，Nginx 不自动转义 —— 生产环境建议配合 map 模块预处理（见下文）

示例：

log_format json '{"time":"$time_iso8601","remote_addr":"$remote_addr","host":"$host","request_uri":"$request_uri","status":$status,"body_bytes_sent":$body_bytes_sent,"http_referer":"$http_referer","http_user_agent":"$http_user_agent","request_time":$request_time,"upstream_response_time":"$upstream_response_time"}';

应用到 access_log 并启用

在 server 或 location 块中调用该格式：

1. 指定日志路径和格式名（如 json），支持追加 buffer 和 flush 提升性能
2. 避免写入 /dev/stdout（除非容器环境且明确重定向），推荐写入文件并由日志采集器读取

示例：

access_log /var/log/nginx/access.json json buffer=32k flush=1s;

处理特殊字符：用 map 预清洗危险字段

$http_user_agent 或 $http_referer 可能含双引号、换行符，直接插入 JSON 会导致解析失败。Nginx 的 map 指令可做简单替换：

1. 在 http 块中定义 map，将双引号、换行、制表符替换为空字符串或占位符
2. 注意 map 是惰性执行，只对匹配变量生效，不影响性能

示例：

map $http_user_agent $ua_json {

default "$http_user_agent";

~"[""nrt]" "invalid_ua";

}

log_format json '{"user_agent":"$ua_json",...}';

验证与调试技巧

JSON 日志是否合法，不能只靠肉眼检查：

1. 用 nginx -t 确认配置语法无误（它不校验 JSON 结构）
2. 触发一次请求后，用 tail -1 /var/log/nginx/access.json | python3 -m json.tool 格式化校验
3. 若报错，常见原因是某个变量为空导致 JSON 缺少引号（如 "ref": $http_referer → "ref": ），务必给所有字符串变量加引号