map未命中default本质是配置或逻辑错误，需检查：①map是否在http块顶层；②源变量值是否为空或格式不符；③default是否显式声明且非空；④正则顺序与语法是否正确。
map变量未命中default，本质是配置写法或执行逻辑出了偏差，不是“漏匹配”，而是Nginx根本没走到default分支——常见原因就那几个，逐项检查基本能定位。
确认map是否定义在http块顶层
map指令只能出现在http { } 块内，不能嵌套在server、location甚至events里。如果放在server中，Nginx启动会直接报错unknown directive "map"；如果侥幸没报错（比如被include进错误位置），该map实际不会生效，变量始终为空，default自然不触发。
- 打开主配置文件（如/etc/nginx/nginx.conf），确认map块位于http { } 大括号内部，且不在任何子块中
- 用nginx -t验证语法，确保无解析错误
- 若使用include引入配置，检查被包含文件是否被正确加载到http上下文
检查源变量值是否为空或格式不符
map匹配依赖源变量的真实取值。如果源变量本身为空（如$arg_token在URL中根本没传）、含不可见字符（如换行、
map匹配依赖源变量的真实取值。如果源变量本身为空（如$arg_token在URL中根本没传）、含不可见字符（如换行、\0）、或大小写/空格与规则不一致，所有正则和字面量都会跳过，default才应兜底——但如果default没写，就真成空了。
）、或大小写/空格与规则不一致，所有正则和字面量都会跳过，default才应兜底——但如果default没写，就真成空了。
- 临时加一条日志：在location中用access_log /var/log/nginx/debug.log main，并定义log_format包含$arg_token $cookie_gray $host等源变量，看实际值是什么
- 注意$arg_*类变量对URL编码敏感，?token=abc%20def中的空格会被解码，但正则若写"abc def"就无法匹配，应改用~*abc\s+def或先用map二次处理
- Cookie值可能带引号或分号，$cookie_xxx默认不含外层双引号，但部分客户端会发gray="on"; path=/，此时需用正则提取：~*\"?on\"?匹配带或不带引号的on
验证default是否存在且位置合理
default不是可选修饰符，是必须显式声明的语句。它不参与顺序匹配，只在所有其他规则失败后生效，但必须写出来——缺了它，未命中时变量就是空字符串，后续proxy_pass、if判断、add_header都可能出错。
- 检查map块末尾是否有default "xxx";，值建议用明确字符串（如"default_upstream"），别用空值或注释占位
- default可以放在任意位置，但推荐放最底下，避免误读；放在中间也不影响逻辑，只要语法正确
- 注意不要写成default;（缺值）或default "";（空字符串），后者虽合法但多数场景下等于没设
排除正则优先级和语法陷阱
正则匹配从上到下逐条尝试，首个成功即终止。如果上面某条宽泛正则（如~*.*)提前吃掉了所有请求，下面的精确规则和default就永远执行不到。
- 把default放在所有正则和字面量之后，确保它是最后兜底项
- 正则必须以~（区分大小写）或~*（忽略大小写）开头，不能漏掉波浪线；写成"*.example.com"是字面量通配，不是正则
- 正则中避免空格，如~* image\/webp错误（斜杠前有空格），应为~*image\/webp
- 用nginx -t能发现语法错误，但无法校验逻辑覆盖度；建议用curl模拟各类请求值，观察$新变量输出
