如何利用Map指令根据客户端特征动态重写特定的响应状态-Nginx-PHP中文网

Map指令不能直接重写状态码，仅能通过error_page+return等机制配合变量映射实现条件状态重写，如按User-Agent、请求头或IP段动态返回429、418或503等状态。

如何利用map指令根据客户端特征动态重写特定的响应状态

Map 指令本身不能直接重写响应状态码，它只负责变量映射，不参与响应生成阶段。Nginx 中修改状态码必须使用 error_page + return 或 proxy_intercept_errors 配合自定义错误页，而 map 的作用是为这些机制提供决策依据——比如根据 User-Agent、IP 地段或请求头，动态决定“是否触发状态码重写”以及“重写成什么值”。

用 map 生成重写策略标识

在 http 块中定义 map，把客户端特征转为可被 error_page 引用的标记变量：

按设备类型区分：移动端 API 请求返回 429，桌面端返回 200
按请求头识别测试流量：携带 X-Debug: rewrite 的请求强制转为 418
按 IP 段控制灰度：内网 IP 访问 /healthz 返回 200，公网 IP 返回 503

示例配置：

map $http_user_agent $rewrite_status {
    ~*android|iphone 429;
    ~*curl|httpie     418;
    default          0;
}

map $remote_addr $ip_policy {
    192.168.0.0/16   200;
    10.0.0.0/8       200;
    default          503;
}

结合 error_page 实现条件状态重写

map 变量不能直接用于 return，但可通过 error_page 将特定状态“中转”为另一个状态。关键技巧是：用一个内部跳转码（如 499）作为中介，再由 error_page 映射到目标状态：

先在 location 中用 if 判断 map 变量非零，执行 return 499（仅作标记，不对外暴露）
用 error_page 499 = $rewrite_status /_rewrite；其中 $rewrite_status 是 map 生成的数字
定义内部 location /_rewrite，用 return $rewrite_status “” 终止并输出目标状态

注意：if 在 location 内可用，且仅用于简单变量判断，符合安全实践。

避免常见陷阱

以下做法不可行或不推荐：

在 add_header 或 proxy_set_header 中尝试设置状态码——无效，状态码由 upstream 或 return/rewrite 指令决定
把 map 变量直接传给 return 指令（如 return $rewrite_status）——Nginx 不支持变量化状态码
在 server 级使用 error_page 重写所有 200 ——会干扰正常流程，应限定在特定 location 内
依赖 $status 变量做 map 输入——它是响应阶段变量，map 在请求解析阶段已执行完毕，无法读取