在 linux 中实现 nginx 平滑重载时 lua 代码同步生效，核心做法是修改 nginx 配置并触发 `nginx -s reload`。nginx 主进程会重新加载配置文件，工作进程（worker）在接收到信号后，会重新执行 `lua_code_cache on` 状态下的 lua 脚本文件。由于 nginx 的 worker 进程是独立运行的，只要确保所有 worker 进程都能读取到更新后的 lua 文件路径，且文件内容已完整写入磁盘，lua 解释器就会在下次请求或预加载阶段加载新代码，从而实现无中断的代码更新。
Nginx 重载机制如何影响 Lua 模块
Nginx 的重载机制依赖于主进程与 Worker 进程的协作。当执行 `nginx -s reload` 时，主进程验证配置语法无误后，会将新的配置传递给现有的 Worker 进程，同时启动新的 Worker 进程。对于 OpenResty 或 ngx_lua 模块而言，Lua 代码通常缓存在内存中。如果 `lua_code_cache` 开启（默认值），Lua 虚拟机不会每次请求都重新读取文件，而是使用缓存。因此，单纯的文件替换不会立即生效，必须通过重载让 Worker 进程重启其内部的 Lua 环境，或者依赖特定的热更新机制。在实际操作中，最稳妥的方式是配合 `lua_shared_dict` 或外部状态管理，但基础的热更新主要依靠进程重启来刷新内存中的 Lua 字节码。
worker_processes 4;
events {
worker_connections 1024;
}
http {
lua_package_path "/usr/local/openresty/lualib/?.lua;/opt/myapp/lua/?.lua;;";
server {
listen 80;
location /test {
content_by_lua_block {
-- 这里引用外部 Lua 文件
local handler = require "my_handler"
handler.run()
}
}
}
}
上述配置展示了标准的 Nginx 结构。关键在于 lua_package_path 指定了 Lua 模块的搜索路径。当 my_handler.lua 文件被修改后，执行 nginx -s reload。旧的 Worker 进程在处理完当前请求后会退出，新的 Worker 进程启动时会重新初始化 Lua 状态机，此时 require "my_handler" 会从磁盘读取最新的 my_handler.lua 文件并编译为字节码。这个过程对客户端是透明的，因为 Nginx 在重载期间保持监听端口不变，新连接会被分配给新启动的 Worker。
如何避免重载期间的配置冲突
在平滑重载过程中，最大的风险在于新旧配置文件的原子性切换以及 Lua 代码的版本一致性。如果 Nginx 配置文件中硬编码了 Lua 文件的具体版本或路径，而 Lua 文件本身发生了不兼容的变更，可能导致部分 Worker 加载旧代码，部分加载新代码，引发逻辑错误。解决这一问题的方法是确保 Lua 代码的幂等性和配置的原子性。建议使用符号链接或临时文件重命名的方式更新 Lua 文件，确保文件系统层面的原子操作。同时，在 Nginx 配置中，应避免在 init_by_lua_block 中加载可能频繁变动的业务逻辑，因为该块仅在 Master 进程启动时执行一次，重载时不会重新执行，除非整个 Nginx 服务完全重启。
# 假设 my_handler.lua 包含以下代码
local M = {}
function M.run()
ngx.say("Handler Version: 2.0")
end
return M
# 更新后的 my_handler.lua
local M = {}
function M.run()
ngx.say("Handler Version: 3.0")
end
return M
为了验证重载效果，可以编写一个简单的测试脚本。首先启动 Nginx，访问 /test 接口，确认输出为 "Handler Version: 2.0"。然后修改 my_handler.lua 中的版本号并保存。接着执行 nginx -s reload。再次访问 /test 接口，如果输出变为 "Handler Version: 3.0"，则说明 Lua 代码已成功同步生效。需要注意的是，如果并发请求较多，可能会观察到部分请求仍返回旧版本，这是因为这些请求被分派到了尚未退出的旧 Worker 进程。随着旧 Worker 处理完毕并退出，所有后续请求都将由加载了新代码的新 Worker 处理，最终达到全局一致。
基于 lua_code_cache off 的特殊情况
如果在开发环境中希望实现真正的“即时”热更新，而不需要执行 nginx -s reload，可以将 lua_code_cache 设置为 off。在这种模式下，Nginx 会在每次请求时重新读取并编译 Lua 文件。这意味着修改 my_handler.lua 后，下一次请求会自动加载最新代码，无需重载 Nginx。然而，这种做法在生产环境中极不推荐，因为它会带来显著的性能开销，每次请求都要进行文件 I/O 和 Lua 字节码编译。此外，它也无法解决 Nginx 配置本身的变更问题。因此，lua_code_cache off 仅适用于调试阶段，生产环境的平滑重载依然依赖 lua_code_cache on 配合 nginx -s reload 的标准流程。
