nginx -t 可检测 log_format 语法错误，包括名称非法、引号/括号不匹配、变量名错误等；需确保名称仅含字母数字下划线短横线、格式字符串用双引号包裹、变量拼写正确且大小写敏感、log_format 定义在 http 块内并先于 access_log 引用。
直接用 nginx -t 即可检测 log_format 的语法错误，它会明确报出拼写、括号不匹配、非法变量等具体问题。
检查 log_format 是否存在基础语法错误
Nginx 对 log_format 的语法要求严格：名称不能含空格或特殊字符（只允许字母、数字、下划线、短横线），日志格式字符串必须用双引号包裹，且所有大括号 {} 和引号必须成对闭合。例如下面这些写法都会被 nginx -t 拒绝：
-
log_format my format "$remote_addr";—— 名称中带空格，报错：invalid number of arguments -
log_format main $remote_addr "$status;—— 引号未闭合，报错：unexpected end of parameter, expecting ";" -
log_format main "$upstream_http_x-$trace_id";—— 变量名含非法连字符，Nginx 不识别该变量，虽不报错但实际输出为空，需结合error_log级别为info或debug查看警告
确认变量名是否真实存在且拼写正确
Nginx 内置变量（如 $remote_addr、$request_time）区分大小写，且不能随意添加前缀或修改结构。常见误写包括：
-
$request_time_ms（不存在）→ 正确是$msec或用$request_time配合log_format中的~格式化（需 1.19.5+） -
$http_user_agent写成$http-user-agent（短横线应为下划线） -
$upstream_addr误作$upstream_address（后者无效）
完整可用变量列表见官方文档 ngx_http_log_module，建议复制粘贴而非手敲。
验证 log_format 是否被 access_log 正确引用
即使 log_format 本身无误，若 access_log 指令中引用的名称拼错，Nginx 同样会报错：
-
log_format main "...";但写了access_log /var/log/nginx/access.log mian;（mian拼错）→ 报错：unknown log format "mian" - 定义在
http块，但在server块中引用了未定义的格式名 → 同样触发unknown log format
注意：log_format 必须定义在 http 块内，且在 access_log 使用前完成定义（顺序敏感）。
开启 debug 日志辅助定位隐性问题
当 nginx -t 通过但日志输出异常（如字段全为空、时间戳错乱），可临时启用 debug 级别日志：
- 在
nginx.conf的http或events块中加入：error_log /var/log/nginx/error.log debug; - 重载配置：
nginx -s reload，观察 error.log 中是否出现类似variable "$xxx" isn't defined或using uninitialized variable的提示 - 调试完成后务必关掉 debug，避免性能和磁盘压力
不复杂但容易忽略
