最轻量高效的nginx重定向方式是在http块顶层用map预定义$redirect_url变量，再通过return 301 $redirect_url实现零开销跳转；map需置于http范围内、按从具体到宽泛顺序书写、建议始终设置default，配合log_format或add_header可调试验证。
直接在 http 块里用 map 定义重定向目标变量，再在 server 或 location 中用 return 301 $redirect_url 引用——这是最轻量、最高效的方式。它把“匹配逻辑”和“执行动作”彻底分离，避免大量 if + rewrite 带来的重复计算开销。
必须写在 http 块顶层
map 不是 location 内的控制指令，而是预处理阶段的变量映射机制。它只能出现在 http { } 范围内，通常放在 include mime.types; 后、server { } 前。写错位置会报错：unknown directive "map"。
- 宝塔用户需手动编辑
/www/server/nginx/conf/nginx.conf，或新建global_vars.map文件并用include加载 - 变量名不带
$：定义时写map $uri $redirect_url { ... }，目标变量叫redirect_url，引用时才写$redirect_url - 所有
map变量自动全局生效，任意server都能直接使用
按顺序首匹配即止，规则要从具体到宽泛
map 匹配不是全量扫描，而是从上到下逐行判断，命中第一条就结束。所以精确规则（如完整路径、正则）必须放前面，模糊规则（如通配符、default）放最后。
- 字面量匹配优先：例如
/old-api/v1/users比/old-api更靠前 - 正则支持捕获：用
~^/v(\d+)/(.+)可提取版本号，在右侧写/api/v$1/$2 - 不区分大小写的正则用
~*，比如~* ^/ADMIN/→/admin/ - 没匹配且没写
default，变量值为空字符串，可能导致 301 跳转失败，建议总加default /;
配合 return 实现零开销跳转
有了 $redirect_url，后续只需一行 return 301 $redirect_url;，Nginx 不需要再做正则解析、条件判断或 location 查找，性能接近 O(1)。
- 不要在
location /里堆多个return，统一交给 map 预计算 - 若需保留原始 query 参数，右侧值写成
$scheme://$host$uri?$args形式 - 可组合多个源变量，比如用
map "$scheme$uri" $redirect_target { ... }避免协议切换带来的重复判断
调试与验证技巧
map 本身不输出日志，但可通过 log_format 和 $redirect_url 把映射结果打到 access log 里，快速确认是否命中预期规则。
- 临时加一句
add_header X-Redirect-To $redirect_url always;，用 curl -I 看响应头 - 修改后务必
nginx -t检查语法，再nginx -s reload生效 - 线上慎用未加
default的 map，空变量可能引发 301 跳转到根路径等意外行为
