map指令用于在Nginx中按域名精准映射HTTPS跳转目标，需定义在http块内，支持default兜底、精确匹配、通配符和正则，配合return 301或proxy_pass实现分域跳转与代理。
直接用 return 301 https://$host$request_uri 虽然能强制跳转，但无法区分不同域名的 HTTPS 目标地址（比如把 www.example.com 跳到 https://example.com，而把 api.example.com 跳到 https://api.example.com:8443）。map 指令正是解决这类“按域名分发跳转目标”的核心工具——它在请求解析早期就生成目标 URL，再配合 return 或 proxy_pass 实现精准控制。
在 http 块中定义域名到 HTTPS 地址的映射
所有 map 必须写在 http{} 块内，不能放在 server 或 location 中。目标是把原始 $host 映射成完整的 HTTPS 地址（含端口、路径前缀等）：
- 用
default设兜底地址，避免未匹配时跳转失败 - 支持精确匹配（如
example.com）、通配符（*.example.com）和正则（如~*^www\.） - 右侧值可拼接变量，比如
"https://$host:8443"或"https://secure.example.com/api"
示例配置：
http {
map $host $https_target {
default "https://example.com";
example.com "https://example.com";
www.example.com "https://example.com";
api.example.com "https://api.example.com:8443";
~*^staging\.(.+)$ "https://staging.$1:8080";
~*^dev-([a-z0-9]+)\.example\.com$ "https://$1-dev.example.com";
}
}
在 server 块中触发跳转或代理
有了 $https_target 变量，就可以在 80 端口的 server 中统一做 301 重定向，或者在反向代理场景中作为 proxy_pass 的目标：
- 纯跳转：用
return 301 $https_target$request_uri;，注意保留原始路径 - 代理转发：当后端只提供 HTTP 服务但需对外暴露 HTTPS 时，
proxy_pass $https_target;配合 SSL 终止即可 - 避免空跳转：确保 map 中有
default，否则未匹配域名会跳到https://导致浏览器报错
典型 server 配置：
server {
listen 80;
server_name example.com www.example.com api.example.com staging.example.com;
location / {
return 301 $https_target$request_uri;
}
}
结合请求头或路径做更精细的跳转判断
单靠 $host 有时不够——比如同一域名下，带特定参数或路径的请求要跳到不同 HTTPS 地址。这时可拼接源变量，让 map 输入更丰富：
- 拼接
$host:$args区分是否含debug=1 - 拼接
$host:$uri实现 “example.com/admin/ → https://admin.example.com” - 正则捕获子域名并重构成新域名，如
client1.example.com → https://client1.portal.example.com
例如：
map "$host:$uri" $advanced_target {
default "https://example.com";
"~*^example\.com:/admin/.*$" "https://admin.example.com";
"~*^example\.com:/api/.*$" "https://api.example.com:8443";
"~*^([^.]+)\.example\.com:/.*$" "https://$1.portal.example.com";
}
验证与调试要点
map 是静态编译的，修改后必须 nginx -t && nginx -s reload 才生效。调试时重点关注：
- 用
curl -I -H "Host: xxx" http://127.0.0.1模拟不同 host 请求，看响应头 Location 是否正确 - 检查 Nginx 错误日志，常见错误是
proxy_pass后跟空变量（因 map 未匹配且无 default） - 正则中特殊字符（点、斜杠、括号）要转义，大小写不敏感用
~*，避免漏匹配 - 若跳转后证书报错，说明目标地址虽对，但后端 HTTPS 服务未正确配置对应域名的证书
