宝塔面板自定义Nginx变量与重定向设置

本文深入讲解了在宝塔面板中高效、安全地为Nginx配置动态变量与智能重定向的四大核心方法：通过`map`指令实现基于域名、参数等请求特征的全局条件判断；利用`include`机制分离变量配置，规避面板升级导致的覆盖风险；借助`geo`指令精准识别IP地域并执行差异化路由；以及结合Lua模块突破原生限制，实现JWT解析、API校验等复杂业务逻辑。每种方案均配有详细操作步骤、典型示例和关键验证技巧，帮助运维人员告别硬编码、提升配置复用性与可维护性，让Nginx在宝塔环境下真正具备企业级灵活调度能力。

如果您在宝塔面板中需要为 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 匹配规则。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《宝塔面板自定义Nginx变量与重定向设置》文章吧，也可关注golang学习网公众号了解相关技术文章。