启用 log_subrequest on 可使 Nginx 将 SSI、mirror、auth_request 等子请求写入 access log，解决其默认不记日志导致的调试盲区；需配合 access_log 使用，子请求可通过 $request_id、$connection_requests、$remote_addr 和 $request 内容识别。
启用 log_subrequest 可让 Nginx 将子请求（subrequest）也写入 access log，这对调试 SSI（Server Side Includes）、mirror 指令、auth_request 或自定义模块发起的内部请求非常关键——否则这些请求默认不记日志，执行路径就像“黑盒”。
为什么子请求默认不记日志？
Nginx 设计上将子请求视为内部逻辑的一部分，而非客户端发起的独立 HTTP 请求。因此，即使子请求实际触发了 upstream 调用（如读取另一个 location、代理到后端、或执行鉴权），access_log 指令默认只记录主请求（main request）。这导致：
- SSI 包含的文件（如
）是否成功加载、耗时多少、返回什么状态码，无法从日志直接看出； - 使用
mirror指令复制流量时，镜像请求是否发出、是否超时或失败，主日志里完全无迹可循； -
auth_request的鉴权子请求若出错（如返回 500），主请求可能静默拒绝，但日志里只看到主请求的 401/403，找不到根因。
如何开启子请求日志记录
只需在 http、server 或 location 块中添加：
log_subrequest on;
注意：log_subrequest 是全局开关，不能按 location 精细控制是否记录子请求日志（Nginx 当前版本不支持）。但它会尊重所在作用域的 access_log 配置——也就是说，只有该作用域启用了 access_log，且同时设置了 log_subrequest on，子请求才会被记录。
例如：
location / {
access_log /var/log/nginx/main.log main;
log_subrequest on; # ✅ 主请求 + 子请求都记入 main.log
}
<p>location /auth {
access_log /var/log/nginx/auth.log auth;</p><h1>log_subrequest 未开启 → 即使有 auth_request 子请求，也不记日志</h1><p>}</p>
识别日志中的子请求：关键字段与标记
启用后，子请求会在 access log 中出现，和主请求格式一致，但可通过两个特征区分：
-
$request_id：如果配置了
log_format包含$request_id，主请求与它的所有子请求共享同一个 ID（前提是子请求未被显式重置）； -
$connection 或 $connection_requests：子请求复用同一连接，但
$connection_requests会递增；更实用的是在log_format中加入$request_length和$body_bytes_sent—— 子请求通常不返回响应体（如 SSI 包含是内联合并的），$body_bytes_sent多为 0； -
无客户端 IP 的痕迹：子请求的
$remote_addr通常是127.0.0.1或上游地址（取决于子请求类型），而主请求是真实客户端 IP； -
特殊 status 标识：Nginx 不额外标记子请求类型，但你可以通过
$request字段内容判断，例如：-
"GET /_ssi/header.html HTTP/1.0"→ SSI 包含触发的子请求； -
"POST /mirror-logger HTTP/1.0"→mirror指令发往镜像 location 的请求； -
"GET /check-auth HTTP/1.0"→auth_request发起的鉴权请求。
-
配合自定义 log_format 提升可追溯性
推荐在 log_format 中加入以下变量，便于关联与过滤：
log_format debug_subreq '$time_local | $request_id | $connection_requests | '
'$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"';
<p>access_log /var/log/nginx/debug.log debug_subreq;
log_subrequest on;</p>
这样每条日志带上了请求序号（$connection_requests）、唯一 ID、上游耗时等，再配合 grep 或日志分析工具（如 Loki + Grafana），就能还原一次 SSI 页面加载中所有子请求的耗时瀑布，或快速定位镜像流量失败的具体环节。
