map指令必须在http块顶层定义，不能嵌套在server或location中；需配合geoip2模块与geolite2-country.mmdb数据库，通过real_ip还原真实ip后，再结合if或proxy_pass实现灰度控制。
Map指令必须在http块顶层定义，不能嵌套在server或location里
很多人把 map 写在 server 块里，Nginx直接报错：unknown directive "map"。这是因为 map 是 http 级模块指令，只允许出现在 http{...} 作用域最外层。
实际配置时，先确保已加载 ngx_http_geoip2_module（推荐）或旧版 ngx_http_geoip_module，然后在 http 块开头附近添加：
http {
# 必须在这里，不能缩进到 server 内
map $geoip2_data_country_code $is_target_region {
default 0;
CN 1;
JP 1;
KR 1;
}
<pre class="brush:php;toolbar:false;"># 后续可基于 $is_target_region 做判断}
注意变量名不能含短横线（-），比如 $geoip-country 是非法的，必须用下划线。
GeoIP2 模块读取的是二进制 GeoLite2-Country.mmdb，不是纯文本 IP 库
旧版 geoip 模块依赖 .dat 文件，而新版 geoip2 强制要求使用 MaxMind 官方发布的 .mmdb 格式数据库。如果误放 GeoLiteCountry.dat，Nginx 启动会失败并报错：invalid database format。
正确做法：
- 从 MaxMind 官网 下载
GeoLite2-Country.mmdb - 放在 Nginx 可读路径，如
/usr/share/GeoIP/GeoLite2-Country.mmdb - 在
http块中显式加载：geoip2 /usr/share/GeoIP/GeoLite2-Country.mmdb { $geoip2_data_country_code source=$remote_addr country iso_code; }
注意 source=$remote_addr 表示直接解析客户端真实 IP；若前端有 CDN 或代理，需先用 real_ip 模块还原真实 IP，否则永远读到的是 CDN 节点地址。
灰度控制要结合 if + return 或 proxy_pass 分流，不能只靠 map 变量
map 本身只是变量映射，不触发任何行为。真正做灰度路由，得配合 if 或 map + proxy_pass 动态 upstream。
常见两种写法：
- 简单拦截（返回特定状态码）：
location /api/ { if ($is_target_region) { return 451; # 或重定向到灰度页 } proxy_pass http://prod_backend; } - 动态后端选择（更常用）：
map $is_target_region $upstream_group { 1 "gray_backend"; 0 "prod_backend"; } upstream gray_backend { server 10.0.1.10:8080; } upstream prod_backend { server 10.0.1.20:8080; } <p>location /api/ { proxy_pass <a href="https://www.php.cn/link/db190973a7de5c5c876cba872133442f">https://www.php.cn/link/db190973a7de5c5c876cba872133442f</a>; }</p>
注意：Nginx 的 if 在 location 外不生效，且 if + proxy_pass 组合有隐式限制（比如不能带 URI 重写），优先选 map 驱动 proxy_pass 的方式。
真实 IP 识别失效会导致地理判断全错，必须验证 $remote_addr 是否可信
只要请求经过任意一层代理（包括云 WAF、CDN、k8s Ingress），$remote_addr 就变成上一跳地址，geoip2 查出来的就是代理机房位置，而非用户所在地。
必须做两件事：
- 启用
real_ip模块还原真实 IP：set_real_ip_from 192.168.0.0/16; set_real_ip_from 203.208.60.0/22; real_ip_header X-Forwarded-For; real_ip_recursive on;
（set_real_ip_from要填你所有可信代理段） - 在
geoip2配置中改用该变量：geoip2 /path/to/GeoLite2-Country.mmdb { $geoip2_data_country_code source=$realip_remote_addr country iso_code; }（变量名取决于你定义的$realip_remote_addr）
没做这一步，灰度规则对海外用户完全失效——他们可能被当成北京用户打到灰度集群，也可能被当成东京用户绕过灰度，问题极难复现。
