自定义日志格式失效主因是log_format定义顺序错误或位置不当——必须置于http块顶层且在access_log引用之前，不可在server/location内定义，否则静默忽略或报错。
自定义日志格式失效，往往不是语法报错，而是配置项顺序不对导致的“静默忽略”——log_format 定义必须出现在 access_log 引用它之前，且不能放在 location 块内（除非明确用于该 location），否则 Nginx 会直接跳过或回退到默认格式。
log_format 必须在 access_log 之前定义
Nginx 按配置文件从上到下解析，遇到 access_log 引用一个尚未定义的 log_format 名称时，不会报错，而是自动降级使用内置的 combined 格式（或默认格式）。这种“不报错却没生效”的情况最易被忽略。
- 错误写法（log_format 在后）：
access_log /var/log/nginx/app.log app_json;
log_format app_json '{ "time": "$time_iso8601", "status": $status }'; - 正确写法（log_format 在前）：
log_format app_json '{ "time": "$time_iso8601", "status": $status }';
access_log /var/log/nginx/app.log app_json;
log_format 不能嵌套在 location 或 server 块内（除非局部作用）
log_format 是全局指令，只允许出现在 http 块顶层。若误写在 server 或 location 内，Nginx 启动时会直接报错：[emerg] "log_format" directive is not allowed here；但若你用了旧版 Nginx（如 1.11.0 之前），部分版本可能静默忽略，导致格式未加载。
- ✅ 正确位置：http 块开头或末尾（但必须在任何 access_log 之前）
- ❌ 错误位置：
server { log_format ...; }或location /api { log_format ...; }
检查是否被同名格式覆盖或拼写不一致
同一个 log_format 名称只能定义一次。若配置中多处定义（比如在 nginx.conf 和 conf.d/*.conf 中都写了 log_format main ...），后加载的会覆盖先加载的——你以为改了格式，实际生效的是另一个文件里的旧定义。
- 用
nginx -T | grep -A 5 "log_format.*your_name"查看完整展开后的所有定义（注意 -T 是大写，输出全部配置） - 确认 access_log 行中引用的名称（如
app_json）与 log_format 行完全一致，包括大小写和下划线 - 避免用保留名如
combined、main自定义覆盖，容易引发意外交互
验证是否真正生效：不要只看日志文件是否存在
即使日志文件成功生成，也不代表你的自定义格式在起作用。最直接的验证方式是：
- 执行
nginx -t确认无语法错误 - 重启或重载：
nginx -s reload - 发一次请求：
curl -I http://localhost/health - 立刻查看日志：
tail -n 1 /var/log/nginx/app.log，观察输出是否符合你定义的 JSON 结构或字段顺序 - 如果仍是空格分隔的 plain 文本，说明格式未加载，优先回头检查顺序和作用域
