nginx变量作用域由声明位置决定:http块声明的变量全局可见,server块声明的仅限本server及子location,location块声明的仅限本location;内置变量如$host、$args等无需声明,各层级均可直接引用,值随请求动态生成。

Nginx 配置中的变量作用域,核心是“声明位置决定可见范围”,不是全局共享,也不自动跨级传递。变量只在它被定义的块及其所有嵌套子块中可用,且不能反向向上或横向访问。
变量声明在哪一级,就在哪一级生效
变量必须用 set 指令显式声明,声明位置直接决定其生命周期和可访问范围:
- 在 http 块中声明(如
set $base_path "/var/www";),该变量对整个 http 块、所有 server 块及其中的 location 块都可见 - 在 server 块中声明(如
set $api_ver "v1";),则仅对该 server 及其内部所有 location 生效,其他 server 不可见 - 在 location 块中声明(如
set $cache_key "$host$request_uri";),只在此 location 内有效,同级或上级 location 无法引用
变量不继承,也不覆盖,只按作用域查找
变量没有“继承”概念,上级块声明的变量,子块可以读取;但子块声明同名变量,不会覆盖上级变量——只是新建一个同名局部变量,两者互不影响:
- http 块设
set $env "prod";,server 块里写set $env "dev";,则该 server 内所有 location 看到的是 "dev",其他 server 仍看到 "prod" - location 中再次
set $env "test";,只影响当前 location,退出后失效,不影响同 server 下其他 location - 变量未声明就使用(如直接写
$missing_var),Nginx 启动或重载时会报错并拒绝加载配置
内置变量不受作用域限制,但值由请求上下文动态决定
像 $host、$remote_addr、$request_uri 这类内置变量,无需声明,任何块中都能直接引用。它们的值不是静态的,而是随每个请求实时生成:
-
$host总是取当前请求 Host 头的值,无论出现在 http/server/location 哪一层,结果都取决于该次请求 -
$arg_xxx解析 query string,$cookie_xxx提取 Cookie,均在运行时计算,与声明位置无关 - 注意:
$scheme、$server_port等可能受 listen 配置或 proxy 设置影响,不是固定值
变量值始终是字符串,且不可修改已有变量值
Nginx 变量本质是只读字符串容器,set 指令每次都是新赋值,不存在“修改”操作:
- 同一块内多次 set 同一变量,以最后一次为准(如先
set $a "1";再set $a "2";,最终值为 "2") - 变量不能用于算术运算或逻辑判断(Nginx 原生不支持),需借助 Lua(OpenResty)或 map 指令间接实现
- map 块定义的变量属于 http 级别,一旦定义,可在所有 server 和 location 中引用,但 map 本身不可嵌套在 server 内











