OpenResty access_by_lua_block中如何调用NGINX $http_upgrade变量

云原生阿岚

2026-11-4

OpenResty 在 access_by_lua_block 中调用 $http_upgrade 变量的实现方法

对应变量映射规则

OpenResty 会将NGINX层定义的所有内置变量统一挂载到ngx.var对象下，不存在单独的特殊命名映射。原NGINX配置中使用的$http_upgrade变量，在Lua代码环境中的对应标识就是去掉前缀$后的http_upgrade，可直接通过对象属性访问。

具体可实现的调用方式

方式1：通过`ngx.var`命名空间直接读取（与NGINX变量行为完全对齐）

这是最贴合原NGINX变量使用习惯的调用方式，直接替换代码块中???的位置即可完成变量引用，示例代码如下：

access_by_lua_block {
    -- 读取对应$http_upgrade变量的值
    local http_upgrade_val = ngx.var.http_upgrade
    -- 可根据业务逻辑做判断，比如识别WebSocket升级请求
    if http_upgrade_val == "websocket" then
        ngx.log(ngx.INFO, "当前请求为WebSocket协议升级请求")
    end
}

方式2：通过请求头读取接口获取

$http_upgrade本质是NGINX对HTTP请求头中Upgrade字段的封装变量，也可以直接通过请求头读取接口获取对应值，示例代码：

access_by_lua_block {
    -- 从请求头列表中获取Upgrade字段值
    local headers = ngx.req.get_headers()
    local upgrade_val = headers["upgrade"]
    ngx.log(ngx.INFO, "从请求头读取到的Upgrade值：", upgrade_val)
}

注意事项

行为差异说明：通过ngx.var.http_upgrade读取时，会自动触发NGINX对请求头的解析逻辑，对请求头的大小写兼容，和在NGINX配置块中直接写$http_upgrade的取值逻辑完全一致。
直接调用ngx.req.get_headers()读取时，接口默认将所有请求头的键名转为小写格式，必须传入小写的upgrade作为键名才能正确取值，使用其他大小写形式容易出现读取为空的问题。