mirror指令必须置于location块内且与proxy_pass并存，不可替代；须配internal防止外部访问，开启mirror_request_body on保留请求体，超时和日志需显式配置，动态路径需用map预定义。
mirror指令必须放在location块里，且不能和proxy_pass共存
镜像流量不是转发，而是“复制一份发给另一个地址”，所以 mirror 不是替代 proxy_pass 的，而是和它并存的。常见错误是把 mirror 写在 server 块或 if 块里，Nginx 会直接报错：nginx: [emerg] "mirror" directive is not allowed here。还有一种典型误用：在同一个 location 里只写 mirror，忘了配 proxy_pass，结果真实请求根本没发出去，镜像倒是发了——线上流量全丢了。
正确做法是：用一个独立的 location 块承接镜像目标（比如 /mirror-api），然后在主业务 location 里同时配置 mirror 和 proxy_pass：
location /api/ {
mirror /mirror-api;
proxy_pass http://upstream;
}
location = /mirror-api {
internal;
proxy_pass http://mirror-backend$request_uri;
}
internal 很关键，它防止外部直接访问 /mirror-api，避免镜像接口被滥用。
镜像请求默认不带原始请求体，POST/PUT 流量会丢数据
默认情况下，mirror 发出的子请求是 GET 方法，且不携带原始请求的 body。这意味着你镜像一个 POST /order 请求时，镜像端收到的是空 body 的 GET 请求，完全失真。
要保留 body，必须开启 mirror_request_body on（Nginx 1.13.4+），并确保主 location 使用 proxy_pass 且后端能接收完整请求体：
-
mirror_request_body on必须写在location块里，全局配置无效 - 开启后，镜像请求方法、headers、body 全部复刻，但原始响应不受影响
- 注意内存开销：大文件上传场景下，Nginx 会缓存整个 body，可能触发
client_max_body_size限制或耗尽 worker 进程内存
镜像失败不影响主链路，但超时和5xx需额外关注
mirror 是异步非阻塞的，镜像请求失败、超时、返回 5xx，都不会影响主请求的处理。这是设计使然，也是“无损”的核心前提。但实际压测中发现两个隐性问题：
- 镜像目标长时间无响应（如卡在 DNS 解析或 connect 阶段），会持续占用 worker 连接，积压多后拖慢整体吞吐
- 镜像服务返回 400/401 等客户端错误，Nginx 默认不记录，容易掩盖镜像端逻辑缺陷
建议在 /mirror-api location 中显式配置超时和日志：
location = /mirror-api {
internal;
proxy_pass http://mirror-backend$request_uri;
proxy_connect_timeout 300ms;
proxy_send_timeout 500ms;
proxy_read_timeout 500ms;
access_log /var/log/nginx/mirror-access.log mirror_fmt;
}
其中 mirror_fmt 可自定义，至少包含 $status 和 $request_time，方便事后排查镜像成功率。
rewrite和变量在mirror路径中不可用，动态目标得靠map
你不能在 mirror 指令里写 mirror /mirror$uri 或 mirror /mirror?id=$arg_id——Nginx 会报语法错误："mirror" directive does not support variables。所有路径必须是静态字符串或通过 map 提前计算好。
如果需要按 host、path 或 header 分流镜像目标，得用 map 构建变量，再在 mirror 中引用：
map $host $mirror_target {
~^staging\. example\.com$ /mirror-staging;
default /mirror-default;
}
server {
location /api/ {
mirror $mirror_target;
proxy_pass http://upstream;
}
}
注意：map 的 key 不支持正则捕获组，也不能嵌套调用；变量值必须是字面量路径，不能拼接 query string。
真实线上最麻烦的点往往不在配置本身，而在于镜像服务能否稳定扛住双倍流量、是否对请求头中的 X-Real-IP 或 Authorization 做了强校验——这些细节不测到生产流量里，根本看不出问题。
