access_log指令仅指定日志存储位置、格式名称及优化参数，真正决定日志内容结构的是log_format指令定义的模板；二者须配合使用，log_format需在http块内预先定义，access_log再引用其名称。
access_log 指令本身不定义日志内容格式，它只负责“把日志写到哪、用什么格式写、怎么优化写”。真正决定每行日志长什么样的，是 log_format 指令定义的格式模板。两者必须配合使用：先用 log_format 命名并声明字段组合，再在 access_log 中引用该名称。
access_log 的基本语法与参数含义
指令格式为：
access_log path [format_name] [buffer=size] [gzip[=level]] [flush=time] [if=condition];
-
path：日志文件绝对路径，如
/var/log/nginx/access.log；Nginx 进程需对该目录有写权限 -
format_name：必须与某个 log_format 定义的名称一致（如
main或detail），不填则默认用内置combined格式 -
buffer：启用内存缓冲，减少磁盘 I/O；例如
buffer=64k表示累积满 64KB 再刷盘 -
flush：即使缓冲未满，也会在指定时间后强制写入；例如
flush=10s防止日志延迟过高 -
gzip：写入前压缩日志（仅支持文件输出），可节省空间但增加 CPU 开销；
gzip=3表示压缩等级为 3 -
if：配合 map 或变量实现条件日志，如
if=$loggable，当 $loggable 为 0 或空字符串时跳过记录
log_format 决定日志内容结构
log_format 是纯文本模板，由 Nginx 内置变量拼接而成。每个变量代表请求生命周期中的一个可观测维度：
-
$remote_addr：直连客户端 IP；若前端有代理，通常需搭配$http_x_forwarded_for获取真实 IP -
$time_local：按本地时区格式化的时间，如[25/Jul/2026:14:22:31 +0800] -
$request：完整请求行，含方法、URI 和协议，如"GET /api/user?id=123 HTTP/1.1" -
$status：响应状态码，用于快速识别失败请求（如 4xx、5xx） -
$body_bytes_sent：实际发给客户端的响应体字节数（不含响应头） -
$request_time：整个请求处理耗时（秒，精度毫秒），对性能分析至关重要 -
$upstream_response_time：后端服务响应耗时，用于定位上游瓶颈 -
$http_user_agent和$http_referer：辅助分析流量来源和终端类型
定义示例：
log_format detail '$remote_addr - $remote_user [$time_local] "$request" '
' $status $body_bytes_sent "$http_referer" "$http_user_agent" '
' $request_time $upstream_response_time $http_x_forwarded_for';
日志输出的实际触发时机
access_log 不是实时逐行写入，而是在请求完成响应后、连接关闭前写入缓冲区。这个过程受以下机制影响：
- 日志写入发生在 请求处理结束阶段，即所有 handler（包括 upstream、filter、log）执行完毕后
- 若启用 buffer，数据暂存内存；达到 size 或超时 flush 时间，才批量落盘
- 如果日志路径所在磁盘满或权限异常，Nginx 默认静默丢弃日志，不会中断服务（可通过 error_log 查看警告）
- 在 server 或 location 块中配置 access_log，会覆盖外层（如 http 块）的同名配置，实现按站点或路径分级记录
常见配置误区与注意事项
- log_format 必须定义在 http 块内，不能放在 server 或 location 中，否则 Nginx 启动时报错
- access_log 的 format_name 名称区分大小写，且必须提前定义，否则使用默认 combined 格式
- 多个 access_log 指令可共存（如同时写主日志和慢查询日志），但需确保路径不冲突、磁盘空间充足
- 高并发下慎用过大 buffer（如 1M+），可能造成内存占用陡增；建议结合 flush 控制延迟与性能平衡
- 若日志中需要包含动态值（如用户 ID），需先用 set 或 map 指令提取并赋值给自定义变量，再在 log_format 中引用
