应使用 Nginx 的 map 指令在 http 上下文中定义全局变量，配合 include 分离配置、geo 实现 IP 区域判断、Lua 模块扩展动态逻辑，并通过自定义日志验证变量生效。
如果您在宝塔面板中需要为 Nginx 配置动态、可复用的重定向行为，仅靠 location 块硬编码难以维护，此时需借助 Nginx 的 map 指令定义全局变量，实现基于请求特征（如域名、路径前缀、参数）的条件判断。以下是具体操作步骤：
一、通过 Nginx 主配置文件定义 map 块
map 指令必须置于 http 上下文中，不能写在 server 或 location 内；宝塔默认不开放直接编辑 nginx.conf 全局配置的入口，因此需手动修改并防止被面板覆盖。该方法适用于需跨多个网站复用同一变量逻辑的场景。
1、使用宝塔面板的【文件】管理器，进入 /www/server/nginx/conf/ 目录。
2、打开 nginx.conf 文件，在 http { } 区块内、include mime.types; 之后、include www.conf; 之前的位置，插入 map 块。例如定义一个根据 Host 头匹配白名单域名的变量 $is_trusted_host：
3、输入以下内容（注意缩进与分号）：
map $host $is_trusted_host {
default 0;
example.com 1;
api.example.com 1;
admin.example.net 1;
}
4、保存文件后，在宝塔面板【软件商店】→【Nginx】→【设置】→【重载配置】，使 map 定义生效。
5、此后可在任意网站的 Nginx 配置中引用 $is_trusted_host 变量，例如在 location /api/ 中添加 if ($is_trusted_host = 0) { return 403; }。
二、在网站配置中使用 include 引入外部变量文件
为避免修改主配置文件导致升级风险，可将 map 定义分离为独立文件，并通过 include 指令加载。该方式便于按项目组织变量，且不会被宝塔自动更新覆盖。
1、在 /www/server/nginx/conf/ 目录下新建文件，命名为 global_vars.map。
2、在该文件中写入 map 定义，例如基于请求 URI 参数控制重定向目标：
map $arg_redirect_mode $redirect_target {
default "/public/landing.html";
"beta" "/beta/index.html";
"dev" "/dev/dashboard.html";
"legacy" "/old/home.php";
}
3、保存后，进入宝塔【网站】列表，点击对应站点【设置】→【配置文件】。
4、在 server { } 块顶部（即 listen 指令上方），添加一行：
include /www/server/nginx/conf/global_vars.map;
5、在需要应用逻辑的 location 块中，使用 rewrite 或 return 引用变量，例如：
location /jump {
return 302 $redirect_target;
}
6、点击【保存】，再点击【重载配置】使变更生效。
三、利用 Nginx 的 geo 指令实现 IP 地域级变量
当重定向需依据客户端真实 IP 所属区域（如国内/海外）时，map 不支持 CIDR 范围匹配，应改用 geo 指令。geo 块同样需置于 http 上下文，且优先级高于 map，适合做访问控制前置判断。
1、编辑 /www/server/nginx/conf/nginx.conf，在 http { } 区块内添加 geo 块（位置同 map）：
geo $client_region {
default "oversea";
include /www/server/nginx/conf/ip_cn.list;
}
2、创建 /www/server/nginx/conf/ip_cn.list 文件，每行一条中国 IP 段，格式为：1.0.1.0/24 cn;
3、在网站配置的 server 块中添加 include 引用（若未在主配置中定义 geo）或直接使用 $client_region 变量。
4、在 location / { } 中添加条件重定向：
if ($client_region = "cn") {
rewrite ^/(.*)$ /zh/$1 break;
}
5、确保网站根目录存在 /zh/ 子路径，否则重定向将返回 404。
四、通过 Lua 模块扩展 Nginx 变量能力
宝塔专业版支持安装 Nginx-Lua 模块（需先安装“Nginx 插件”中的 lua-resty-core），可编写 Lua 脚本生成动态变量，例如解析 JWT token、调用外部 API 校验权限、组合多字段生成唯一路由键等。此方法突破 Nginx 原生指令限制，适用于高度定制化逻辑。
1、确认已安装 Nginx-Lua：进入【软件商店】→【Nginx】→【设置】→【安装插件】，勾选并安装 lua-resty-core 和 lua-resty-redis（如需缓存）。
2、在 /www/server/nginx/conf/ 下新建 lua/ 目录，并创建 auth_logic.lua 文件。
3、在文件中编写 Lua 函数，例如：
function get_redirect_path()
local host = ngx.var.host
local uri = ngx.var.uri
local uid = ngx.var.arg_uid or "guest"
if string.match(host, "beta%.") then
return "/beta/" .. uid .. uri
else
return "/prod/" .. uid .. uri
end
end
4、在网站配置的 server 块中添加：
set_by_lua_file $dynamic_path /www/server/nginx/conf/lua/auth_logic.lua;
5、在 location 中使用该变量：
rewrite ^(.*)$ $dynamic_path last;
6、重启 Nginx 服务以加载 Lua 环境。
五、验证变量是否正确加载与生效
Nginx 变量定义后无法通过日志直接输出原始 map/geo 值，需借助 log_format 或调试响应头进行验证。此步骤用于确认变量已成功注入且值符合预期，避免因拼写错误或作用域问题导致逻辑失效。
1、在 nginx.conf 的 http { } 块中添加自定义日志格式：
log_format debug_log '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$is_trusted_host" "$redirect_target" "$client_region"';
2、在对应网站的 server 块中，将 access_log 指向该格式：
access_log /www/wwwlogs/example_debug.log debug_log;
3、保存配置并重载 Nginx，随后发起测试请求（如 curl -H "Host: example.com" http://your-server/jump?redirect_mode=beta）。
4、查看 /www/wwwlogs/example_debug.log，检查最后三列是否输出预期值，例如：1、1、cn。
5、若某列为短横线（-）或空字符串，说明该变量未定义、未匹配或作用域错误，需回溯 map/geo 块位置及 key 匹配规则。
