init_by_lua_block用于master进程启动前的全局初始化，可加载配置、预热缓存、创建共享字典，但不能修改Nginx配置结构或动态添加server/location块。
Nginx 的 init_by_lua 指令（现推荐使用 init_by_lua_block）确实可用于在 master 进程启动、worker 进程 fork 之前执行 Lua 代码，常被用来做全局初始化，比如加载配置、预热缓存、建立共享字典或连接池等。但它**不能直接用于“初始化 Nginx 自身的 http 块配置”**（如动态添加 server、location 或修改内置指令行为），因为此时 Nginx 配置已解析完毕，语法树已固化。
init_by_lua 的真实作用范围
它运行在 Nginx 配置加载之后、事件循环开始之前，属于 Lua 环境的“早期初始化阶段”。可安全执行的操作包括：
- 初始化
ngx.shared.DICT共享内存字典（如ngx.shared.config:flush_all()或预设初始值） - 加载外部配置文件（JSON/YAML/TOML）并存入共享字典或全局 Lua table，供后续请求读取
- 建立全局连接池（如 Redis、MySQL 连接池），但注意：这些连接属于 master 进程上下文，不能被 worker 进程复用；实际应放在
init_worker_by_lua*中为每个 worker 单独初始化 - 设置全局 Lua 变量或模块缓存（如
package.loaded["myconf"] = require "myconf"）
常见误用与注意事项
以下做法是无效或危险的：
- 试图修改 Nginx 配置结构：Lua 无法在运行时增删 server/location 块，也不能改变 rewrite、proxy_pass 等指令的语义
-
在 init_by_lua 中调用阻塞 I/O（如
io.open同步读大文件、未设超时的http:request()）：会阻塞 master 进程启动，导致 nginx -t 或 reload 失败 -
依赖未就绪的环境：此时日志模块未完全初始化，
ngx.log(ngx.ERR, ...)可能不输出；也不建议在此阶段打大量日志 - 混淆 init_by_lua 和 init_worker_by_lua：前者只运行一次（master 进程），后者每个 worker 启动时各运行一次，连接池、定时器、本地缓存预热等应放后者中
实用初始化示例（加载外部 JSON 配置）
假设你有一个 /etc/nginx/conf.d/app-config.json：
{
"api_timeout": 3000,
"backend_hosts": ["10.0.1.10", "10.0.1.11"]
}在 http 块中写：
lua_package_path "/path/to/lua/?.lua;;";
<p>init_by_lua_block {
local cjson = require "cjson"
local file = io.open("/etc/nginx/conf.d/app-config.json", "r")
if file then
local content = file:read("*all")
file:close()
local config = cjson.decode(content)
-- 存入共享字典，供所有 worker 访问
local dict = ngx.shared.config
dict:set("app_config", config, 0) -- 0 表示永不过期
else
ngx.log(ngx.WARN, "failed to load app-config.json")
end
}</p><p>server {
location /api/ {
content_by_lua_block {
local config = ngx.shared.config:get("app_config")
if config then
ngx.var.upstream_timeout = config.api_timeout
-- 实际转发逻辑需配合 balancer_by_lua* 或变量控制
ngx.say("Using backend hosts: ", table.concat(config.backend_hosts, ", "))
else
ngx.exit(500)
end
}
}
}替代方案：真正动态化路由与配置
若目标是“根据外部配置动态决定 upstream 或路由规则”，推荐组合使用：
-
init_worker_by_lua_block：每个 worker 初始化自己的连接池和本地缓存 -
balancer_by_lua_block：在 upstream 阶段动态选择后端（支持健康检查、权重、一致性哈希） -
set_by_lua_block+map或变量透传：在 rewrite 阶段计算变量，驱动 proxy_pass 或内部跳转 - 配合 etcd/Consul +
lua-resty-etcd：实现配置热更新（通过定时拉取或 watch 机制）
init_by_lua 是强大而有限的入口点——它适合做“一次性的、无副作用的、非阻塞的”准备动作，不是配置引擎。把初始化逻辑分清层级（全局/worker/请求）、区分数据与行为、避免阻塞和跨进程误用，才能稳定发挥 OpenResty 的优势。
