map指令必须定义在http块顶层，不能出现在server或location中；它通过字符串匹配（含正则）将源变量映射为目标变量，用于后续条件控制。
map 指令不是 if，别在 server 块里直接写条件判断
map 是变量映射指令，必须定义在 http 块顶层，不能嵌套在 server 或 location 里。很多人误以为它像 if 那样可随处写，结果 reload 时直接报错：nginx: [emerg] "map" directive is not allowed here。
正确做法是：先在 http 块中声明一个映射关系，把 JA3 指纹哈希值转为布尔标记或等级值；再在 server 或 location 中用这个变量做判断。
-
map只支持字符串匹配（包括正则），不支持数值比较或逻辑组合 - 映射目标变量（如
$ja3_blocked）在首次被引用前不会计算，无性能浪费 - 所有
map块共享同一作用域，变量名不能重复，否则后加载的会覆盖前一个
如何从 $http_x_forwarded_for 或 $binary_remote_addr 关联 JA3？
Nginx 本身不解析 TLS 握手，JA3 指纹需由前置设备（如 WAF、TLS 代理、eBPF 探针）注入请求头。常见做法是让边缘网关把计算好的 JA3 值塞进 X-JA3-Fingerprint 头，Nginx 再读取：
假设你已通过外部模块或反向代理注入该头，则配置如下：
http {
map $http_x_ja3_fingerprint $ja3_blocked {
default 0;
"a1b2c3d4e5f678901234567890abcdef" 1;
"fedcba09876543210987654321cba21f" 1;
~*^deadbeef 1;
~*^badbot.*v2 1;
}
}
注意点：
-
$http_x_ja3_fingerprint是自动将请求头X-JA3-Fingerprint转成小写下划线命名的内置变量 - 正则匹配必须加
~*前缀，且只对原始头值生效，不经过 URL 解码 - 若上游未传该头，
$http_x_ja3_fingerprint为空字符串，会命中default分支
配合 limit_req 或 return 实现拦截，别用 if($ja3_blocked) { return 403; }
直接在 location 里用 if 判断 map 出来的变量，看似合理，但 Nginx 官方明确警告：if 在 location 中有不可预测行为，尤其与 limit_req、proxy_pass 共存时易导致规则失效或 500 错误。
更可靠的做法是结合 limit_req 的拒绝能力，或用 map 输出状态码后统一处理：
map $ja3_blocked $block_status {
0 0;
1 403;
}
server {
location / {
limit_req zone=ja3_block burst=1 nodelay;
limit_req_status $block_status;
proxy_pass http://backend;
}
}
说明：
- 定义一个
limit_req_zone时，key 可以是$ja3_blocked，但更推荐用$http_x_ja3_fingerprint本身，避免 map 层级过深 -
limit_req_status支持变量，但仅限于 4xx/5xx 状态码，且该变量必须在http块中提前定义好 - 如果只想封禁不计数，用
return $block_status更轻量，但注意它会终止后续所有指令（包括日志记录）
JA3 指纹更新快，map 列表怎么热加载不 reload？
硬编码在配置里的指纹列表无法动态更新。每次增删都要 nginx -s reload，高流量场景下可能触发连接重置或短暂 502。
可行解法只有两个：
- 用
include引入外部文件，例如map $http_x_ja3_fingerprint $ja3_blocked { include /etc/nginx/conf.d/ja3_blacklist.map; }，然后只touch该文件 +nginx -s reload（仍需 reload，但变更范围可控） - 放弃
map，改用lua-resty-core的ngx.var+ Redis 查询，实现毫秒级黑名单刷新，但引入 Lua 依赖和额外组件
真正容易被忽略的是：JA3 指纹本身不具备强唯一性，同一浏览器不同插件组合、不同网络栈（如 Go net/http vs curl）会产生不同指纹；盲目封禁可能误伤正常用户。建议始终搭配 $binary_remote_addr 和请求频次做二次校验，而不是单靠 JA3 一锤定音。
