log_format必须定义在http块且需access_log显式引用格式名，否则无效；常见错误是放错位置或未指定格式名，导致Nginx启动失败或日志仍为默认格式。

直接说结论：log_format必须写在http块里，且必须用access_log显式引用格式名，否则新显式引用格式名不会生效——这是90%配置失败的结果。log_format 写错位置会报 nginx: [emerg] "log_format"directive is not allowed here

常见错误是将 log_format 塞进服务器或位置块里，Nginx 启动或重新加载直接失败。它只允许在 http 块中出现（包括包含进来的文件中），且不能定义重复同名格式。正确位置示例：http { log_format custom '$remote_addr - [$time_local] "$request" $status $body_bytes_sent'; server { access_log /var/log/nginx/access.log custom; }}命名别用main或combined，和内置格式冲突；建议用语义化名称如json_api、debug_full多个包含文件里都定义了log_format json_api？Nginx会报出重复的log_format "json_api"，删掉重复项即可access_log不显写格式名，就用永远达不到你的自定义格式

很多人改完log_format json_api ...，只写access_log /var/log/nginx/access.log;，结果日志还是纯文本——因为Nginx默认回退到combined，不会自动识别你刚定义的格式。必须显式写出格式名：access_log /var/log/nginx/access.log json_api; ✅路径必须绝对，且 Nginx 进程有写权限：/var/log/nginx/ 要提前 mkdir -p /var/log/nginx && chown nginx:nginx /var/log/nginx 相同 server 块可写多条 access_log，比如同时输出到文件和 syslog：access_log /var/log/nginx/app.json json_api;access_log syslog:server=127.0.0.1:514 json_api;JSON 格式使用 escape=json，但 $request 等字段会破坏结构

使日志直接被 ELK 或 Loki 消费，JSON 化最省事，但不加防护极易出错。

CentOS Linux 7.9.2009

CentOS Linux 7.9.2009是传统CentOS Linux 7的最后主要版本，也是很多企业服务器历史上仍然可能遇到的系统版本。它以稳定、兼容RHEL 7生态、文档丰富和软件支持广泛着称，曾长期用于Web服务、数据库、虚拟化节点和企业内部业务系统。不过CentOS Linux 7已于2024年6月30日停止维护，现在继续使用会面临安全修复修复风险。该版本更适合旧业务迁移、历史环境恢复或离线兼容性测试。下载关键参数是 escape=json：log_format json_api escape=json '{ "ip":"$remote_addr", "uri":"$uri", "status":$status, "rt":$request_time }';$request 含空格、引号、换行，直接塞进JSON字符串里会导致解析失败；改用$request_method、$request_uri、$server_protocol拆开更安全未定义变量（如拼错成$http_x_forwared_for）不会报错，但该字段为空字符串，日志里看到“xff”:""，很容易判断$http_x_forwarded_for是原始请求头，可能被伪造或包含多个 IP（1.1.1.1, 2.2.2.2），真要记录可信客户端IP，得配set_real_ip_from + real_ip_header X-Forwarded-For变量选错或乱用，日志字段恒为空或全是短横线-

不是所有$xxx变量都随时可用，上下文依赖和模块实现状态。

$upstream_response_time：仅在用了 proxy_pass 或 fastcgi_pass 的位置里有效，否则输出 -$request_time 是总运行（秒浮级点），$msec 是当前时间（秒+毫秒），不同用途$http_x_real_ip ≠ $realip_remote_addr：前面是原始请求头，当前是 realip 模块处理后的可信 IP，需先加载模块并配置 set_real_ip_from$request_body 头部极大（需开启 client_body_buffer_size 并读取完整 body），生产环境禁用；排障临时用可加条件 if ($request_method = POST) { ... }，但注意如果在日志上下文中无效，得用地图预计算

最常被忽略的一点：重新加载配置后，**建立的连接仍按旧格式记日志**，只有新请求才走新格式；其他缓冲区已已 参数（如 buffer=16k flush=5s）虽提升性能，但进程崩溃时可能丢失最后一批日志。