在 nginx 中配置和使用 lua 模块，核心步骤是加载 openresty 或 ngx_lua 模块，并在 nginx 配置文件中通过 lua_package_path 指定脚本路径，随后在 location 块中使用 content_by_lua_block 编写处理逻辑。这样做可以直接在请求生命周期中执行 lua 代码，实现动态响应生成、访问控制或数据转换，而无需重启 nginx 即可热更新逻辑。
Nginx 如何加载并初始化 Lua 环境
要让 Nginx 支持 Lua，必须在主配置文件 nginx.conf 的 http 块中引入必要的指令。首先使用 load_module 加载动态模块（如果是编译为静态则省略），然后设置 lua_package_path 告诉解释器去哪里找 Lua 库。接着在 server 块中定义监听端口，并在具体的 location 中嵌入 Lua 代码。这一步骤建立了从 HTTP 请求到 Lua 虚拟机执行的桥梁。
events {
worker_connections 1024;
}
http {
# 加载 lua 模块 (以 openresty 为例)
load_module modules/ngx_http_lua_module.so;
# 指定 lua 脚本搜索路径
lua_package_path "/usr/local/openresty/lualib/?.lua;/etc/nginx/lua/?.lua;;";
server {
listen 80;
server_name localhost;
location /hello {
content_by_lua_block {
ngx.say("Hello, Lua!")
}
}
}
}
上述配置中，lua_package_path 使用了类似 Lua 标准库的路径分隔符 ; 和通配符 ?。当请求 /hello 时，Nginx 会调用 content_by_lua_block 中定义的匿名函数。该函数执行后，通过 ngx.say 输出内容并自动添加换行符。如果路径配置错误，Lua 解释器将无法找到所需的库文件，导致请求返回 500 错误。
Lua 代码如何在请求生命周期中执行
Lua 代码的执行时机由特定的指令决定，最常用的是 content_by_lua_block，它在内容生成阶段运行。除了内容生成，还可以使用 access_by_lua_block 进行权限检查，或使用 header_filter_by_lua_block 修改响应头。这些指令可以单独使用，也可以组合使用，形成完整的工作流。例如，先检查访问权限，再获取数据，最后生成响应。
location /api/data {
access_by_lua_block {
-- 简单的访问控制示例
if ngx.var.arg_token ~= "secret" then
ngx.exit(403)
end
}
content_by_lua_block {
local args = ngx.req.get_uri_args()
local name = args.name or "Guest"
ngx.header["Content-Type"] = "application/json"
ngx.say('{"message": "Hello ' .. name .. '"}')
}
}
在这个例子中，access_by_lua_block 首先检查 URL 参数中的 token。如果令牌不匹配，直接通过 ngx.exit(403) 终止请求，后续的 content_by_lua_block 不会执行。如果令牌正确，则进入内容生成阶段，解析 URI 参数并构建 JSON 响应。这种分层执行机制允许开发者将逻辑解耦，提高代码的可维护性和安全性。
如何处理 Lua 脚本中的局部变量与作用域
在 Nginx Lua 模块中，变量的作用域遵循 Lua 的标准规则，即默认全局可见，除非使用 local 关键字声明为局部变量。在处理高并发请求时，正确使用局部变量至关重要，因为每个请求都有独立的 Lua 状态机实例，但全局变量如果在多个请求间共享且未加锁，可能导致数据竞争。因此，建议在脚本内部优先使用局部变量存储中间结果，仅在需要跨请求共享时才考虑使用共享字典 ngx.shared.DICT。
