log_format必须定义在http块内且不可重名，JSON化需用escape=json并显式引用格式名；真实IP需配合set_real_ip_from等指令才可靠。
直接说结论：log_format 必须定义在 http 块内，且必须用 access_log 显式引用格式名；JSON 化只需加 escape=json，但要注意变量值含双引号或换行会破坏 JSON 结构，真实 IP 需配合 set_real_ip_from 才可靠。
log_format 必须放在 http 块里，且不能重名
把 log_format 写进 server 或 location 会报错：unknown directive "log_format"。常见错误是复制粘贴时误塞进 server { ... } 开头，或者多个 include 文件里都定义了同名格式（比如两次 log_format main），Nginx 启动直接失败：duplicate log_format "main"。
命名建议用语义化名称，比如：log_format json_access escape=json '{ "ip":"$remote_addr", "time":"$time_iso8601", "method":"$request_method", "uri":"$uri", "status":$status, "rt":$request_time, "ua":"$http_user_agent", "xff":"$http_x_forwarded_for" }';
-
escape=json是关键，它会对变量值自动转义双引号、反斜杠、换行等 - 不要用
$request直接拼 JSON，它可能含空格、引号、换行，极易导致解析失败 - 避免在 JSON 字段里写未定义变量（如拼错成
$http_x_forwared_for），日志中该字段会为空字符串，但不会报错
access_log 必须显式指定格式名，否则 fallback 到 combined
很多人改完 log_format json_access，只写 access_log /var/log/nginx/access.log;，结果日志还是 plain text —— 因为 Nginx 默认只认内置的 combined 和 main，其他格式必须显式写出名字：
access_log /var/log/nginx/access.log json_access; ✅access_log /var/log/nginx/access.log; ❌（实际用的是 combined）
- 同一配置层级（
http/server/location）可写多条access_log，比如同时输出到文件和 syslog：access_log /var/log/nginx/app.json json_access; access_log syslog:server=127.0.0.1:514 json_access; - 路径必须绝对且目录可写，比如
/var/log/nginx/要提前mkdir -p /var/log/nginx && chown nginx:nginx /var/log/nginx - reload 后新请求才走新格式，已有连接仍按旧格式记日志
真实客户端 IP 在 JSON 日志里怎么写才靠谱
仅靠 $http_x_forwarded_for 不安全：它可能被客户端伪造，也可能被中间代理拼接多个 IP（如 1.1.1.1, 2.2.2.2, 3.3.3.3）。真正可靠的方案是组合使用：
在 http 块里加：set_real_ip_from 10.0.0.0/8; set_real_ip_from 172.16.0.0/12; real_ip_header X-Forwarded-For; real_ip_recursive on;
-
set_real_ip_from指定可信代理网段，只有来自这些网段的请求，Nginx 才信任其X-Forwarded-For -
real_ip_recursive on表示逐层剥离，取最左边那个非可信网段的 IP（即原始客户端 IP） - 之后就可以放心用
$remote_addr—— 它此时已是真实 IP，而不是最后一跳代理的地址 - 如果仍想保留原始
X-Forwarded-For全字段，可在 JSON 里额外加"xff":"$http_x_forwarded_for"，但别把它当唯一依据
JSON 日志的坑：解析失败常因这三处
即使加了 escape=json，JSON 解析仍可能失败，主要因为：
-
$http_user_agent或$http_referer含不可见控制字符（如 \u0000、\r\n），escape=json不处理它们，需用map过滤或后端清洗 - 日志行末尾多了空格或逗号（比如手误多敲一个
,在 JSON 最后），整个 JSON 就非法 - 没关掉 gzip 日志压缩（
access_log ... gzip），会导致tail -f看不到实时内容，也难用jq直接解析
验证是否真 JSON：挑一行日志，用 echo '...' | jq -n . 测试；批量检查可用 awk '{print $NF}' /var/log/nginx/access.log | head -100 | jq -R . 2>/dev/null | wc -l 看能成功解析几行。
