nginx作为使用最广泛的Web服务器之一，其日志系统是排查问题、分析流量、安全审计的重要依据。很多初学者只知道默认配置能用，却不清楚日志格式怎么自定义、错误日志级别如何选择、日志文件太大怎么办。本文围绕nginx的log配置展开，从基础语法到进阶技巧，配合完整示例，把日志配置这件事讲透。
nginx日志的基本组成：access_log与error_log
nginx的日志主要分为两类：访问日志access_log和错误日志error_log。访问日志记录每一次客户端请求的信息，包括来源IP、请求时间、请求行、状态码、响应字节数、耗时等；错误日志则记录nginx运行过程中出现的异常、告警和调试信息，比如配置加载失败、上游超时、权限不足等。
两条指令都可以出现在http、server、location等配置块中，作用域遵循就近覆盖原则。也就是说，在server块里重新定义access_log，会覆盖http块里的全局设置，这给我们按站点、按路径独立记录日志提供了便利。
最简单的配置写法如下：
http {
# 访问日志，main是预定义格式名
access_log /var/log/nginx/access.log main;
# 错误日志，路径后面的参数是日志级别
error_log /var/log/nginx/error.log warn;
server {
listen 80;
server_name ippipp.com;
# 单独为这个站点记录日志
access_log /var/log/nginx/example.access.log main;
location /static/ {
# 静态资源不记录访问日志，减少磁盘写入
access_log off;
}
}
}需要注意，如果不想记录某个location的日志，直接写access_log off即可，这比事后清理日志要省事得多。error_log则没有off选项，最低可以设为error_log ... crit;来大幅减少输出量。
log_format自定义日志格式详解
nginx内置了几种日志格式，默认的combined格式包含远程地址、远程用户、时间、请求行、状态码、字节数、Referer和User-Agent。但实际业务往往需要更多信息，比如请求耗时、上游响应时间、真实客户端IP等，这时就需要用log_format自定义格式。
log_format指令只能在http块中定义，第一个参数是格式名称，后面是用引号包裹的格式字符串，内部可以使用大量nginx内置变量。下面是一个实用的扩展格式示例：
http {
log_format main_ext '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent" '
'rt=$request_time uct=$upstream_connect_time '
'uht=$upstream_header_time urt=$upstream_response_time '
'fw=$http_x_forwarded_for cs=$bytes_sent';
access_log /var/log/nginx/access.log main_ext;
}这个格式在默认基础上追加了几个关键变量：$request_time表示nginx处理请求的总耗时，$upstream_connect_time是与后端建立连接的耗时，$upstream_header_time是收到后端响应头的耗时。通过这几个时间字段，可以快速判断慢在哪个环节——连接慢通常是后端负载或网络问题，响应头慢则是后端处理慢，这对性能定位非常有价值。
如果前面有CDN或负载均衡，直接取$remote_addr拿到的往往是代理IP，此时应该解析$http_x_forwarded_for或使用realip模块的$realip_remote_addr来还原真实客户端地址，否则统计和风控都会失真。
错误日志级别选择与调试技巧
error_log的级别从低到高分为debug、info、notice、warn、error、crit、alert、emerg。设置的级别决定了记录的范围：设为warn时，warn及更严重的日志都会写入。生产环境推荐使用warn或error级别，级别太低会产生海量无用信息，级别太高又可能漏掉关键告警。
排查疑难杂症时，可以把级别临时调到debug，配合编译时的--with-debug参数启用调试日志。调试日志会输出请求处理的每个阶段细节，包括upstream选择、缓存命中、重写规则匹配等，是定位诡异问题的终极手段。但要切记调试完立即调回，因为debug级别的磁盘写入量非常大，高并发下会明显拖累性能。
# 调试时临时开启，务必记得排查完改回来
error_log /var/log/nginx/error.log debug;
# 可以针对特定客户端IP只记录debug日志，减少干扰
events {
debug_connection 192.168.1.100;
}error_log同样支持多个实例同时存在，比如全局一个写emerg级别，站点级别一个写error级别，再临时挂一个debug级别的，分层次管理日志输出。
日志切割与logrotate配置实践
nginx自身不会切割日志文件，日志会无限增长，单个文件几GB时不仅打开分析困难，grep和传输都很慢。标准做法是配合系统的logrotate工具按天切割，并利用nginx的USR1信号实现无缝切换。
logrotate的核心逻辑是：把旧日志重命名成带日期的新名字，然后通知nginx重新打开日志文件。因为Linux下文件是按inode引用的，单纯mv之后nginx仍会往旧inode写入，所以必须发送信号让nginx重新打开文件描述符：
# /etc/logrotate.d/nginx 示例配置
/var/log/nginx/*.log {
daily
rotate 30
missingok
notifempty
compress
delaycompress
dateext
sharedscripts
postrotate
[ -f /var/run/nginx.pid ] && kill -USR1 $(cat /var/run/nginx.pid)
endscript
}这段配置的含义是：每天切割一次，保留30份历史，切割后延迟压缩最新的那一份（避免nginx还没写完就压缩），通过USR1信号通知master进程重开日志。也可以不依赖logrotate，用crontab加shell脚本按日期重命名日志并发信号，思路完全一致。
对于超大流量站点，还可以在nginx层面用open_log_file_cache指令缓存日志文件描述符，减少频繁open/close带来的开销：
http {
open_log_file_cache max=10 inactive=20s valid=1m min_uses=2;
}常见问题排查与注意事项
问题一：修改了log_format却不生效。log_format必须在http块定义，且格式名不能与已有名称重复。修改后要执行nginx -t检查语法，再nginx -s reload平滑重载。另外注意变量拼写错误会导致nginx启动失败，比如把$request_time写成$requesttime。
问题二：日志文件权限不足写不进去。如果worker进程以nobody等低权限用户运行，而日志目录属于root，就会出现日志静默丢失的情况。解决办法是确保日志目录对worker用户可写，或者统一由root启动master、以合适用户运行worker。
问题三：磁盘被日志写满。高流量站点一天产生几十GB日志很常见，除了做好轮转压缩，建议把错误日志级别调到error以上，关闭健康检查、静态资源等无意义请求的访问日志，必要时用access_log ... buffer=64k flush=5s;开启缓冲写入，批量刷盘能显著降低IO压力。
# 开启缓冲写日志，64KB缓冲，每5秒强制落盘 access_log /var/log/nginx/access.log main buffer=64k flush=5s;
练习建议：动手是掌握配置最快的路径。可以尝试以下练习：为本机nginx自定义一个包含请求耗时和上游时间的日志格式；配置logrotate实现按天切割并验证USR1信号效果；用GoAccess或awk统计access日志中TOP10的访问IP和慢请求分布。做完这三个练习，nginx日志配置基本就烂熟于心了。
总结一下，nginx日志配置的核心是log_format定义格式、access_log和error_log控制输出位置与级别，再配合logrotate做轮转、缓冲写降低IO、按需关闭无用日志。把这些细节做规范，日志才能真正做到可查、可分析、可长期留存，为线上问题排查和业务分析提供坚实的数据基础。
nginx日志配置access_loglogrotate修改时间：2026-09-06 18:47:32