在 nginx 配置文件中,变量定义通过赋值操作符 = 实现,其生效机制是“惰性求值”与“上下文隔离”。这意味着变量仅在引用它的指令执行时才会被计算,且不同配置块(如 server、location)拥有独立的变量作用域。要确保变量按预期生效,必须明确指定赋值位置,并理解其在请求处理生命周期中的行为。

如何在全局或 Server 块中定义并使用变量
若要在所有虚拟主机或全局范围内共享一个变量,应将其定义在 http 块中。Nginx 会为该变量创建一个全局实例,任何嵌套的 server 或 location 块都可以读取它。如果子块中定义了同名变量,则会覆盖全局变量,形成局部作用域。这种层级关系决定了变量的可见性和优先级。

http {
# 全局变量定义
set $global_var "hello";
server {
listen 80;
server_name example.com;
location / {
# 读取全局变量
add_header X-Global $global_var;
# 局部变量覆盖
set $local_var "world";
add_header X-Local $local_var;
}
}
}上述配置中,$global_var 在 http 块中定义,因此在 server 和 location 中均可访问。而 $local_var 仅在 location 内有效。当请求到达时,Nginx 会先查找局部变量,若未找到则向上层作用域查找。最终响应头将包含 X-Global: hello 和 X-Local: world。
如何在 Location 块中定义局部变量并影响请求处理
在 location 块中定义的变量仅对该块及其内部嵌套的子块有效。这种局部性常用于根据特定路径或条件动态设置变量值,例如重写 URL 或设置自定义头。由于 set 指令的执行顺序依赖于配置块的嵌套结构,因此需确保赋值发生在引用之前。

server {
listen 80;
server_name example.com;
location /api {
set $api_version "v1";
proxy_pass http://backend_v1;
}
location /api/v2 {
set $api_version "v2";
proxy_pass http://backend_v2;
}
location / {
# 此处 $api_version 未定义,值为空
add_header X-Version $api_version;
}
}在该示例中,/api 和 /api/v2 分别设置了不同的 $api_version 值,并指向不同的后端服务。根路径 / 未定义该变量,因此 X-Version 头将为空。这体现了 Nginx 变量作用域的严格隔离:每个 location 块独立维护其变量状态,互不干扰。
基于 set 指令在 if 块中赋值的特殊行为问题
在 Nginx 中,if 块内的变量赋值具有特殊性:它在 if 块执行结束后不会保留到外层作用域。这是因为 if 块在 Nginx 内部被视为一个独立的配置上下文,其变量生命周期仅限于块内。若需在外部使用条件结果,应避免在 if 中赋值,改用其他机制。
server {
listen 80;
server_name example.com;
location /test {
set $result "default";
if ($request_uri ~* "/admin") {
set $result "admin_access";
}
# 此处 $result 仍为 "default",因为 if 块内的赋值未传播
add_header X-Result $result;
}
}上述代码中,即使请求 URI 匹配 /admin,X-Result 头仍显示 default。这是 Nginx 的经典陷阱:if 块内的 set 指令不影响外层变量。正确做法是使用 map 指令或重构逻辑,避免依赖 if 块的状态传递。


















