rewrite_by_lua 是 OpenResty 中运行于 Nginx rewrite 阶段（第4阶段）的核心 Lua 执行阶段，用于动态改写 URI、参数或变量以实现路由重写、灰度分发等，支持修改 ngx.var.uri 等变量影响后续 location 匹配，但不可返回响应体，需注意变量可写性、异步 I/O 及错误捕获。
rewrite_by_lua 是 OpenResty 中最常用、也最关键的 Lua 执行阶段之一，它运行在 Nginx 的 rewrite 阶段（早于后端转发和 content 处理），专用于动态干预请求路径、参数或头信息，不依赖外部服务即可完成路由重写、灰度分发、权限预检等逻辑。
rewrite_by_lua 的执行时机与定位
它在 Nginx 请求处理流程中处于第 4 阶段（rewrite 阶段），紧随 server-rewrite 和 find-config 之后，早于 access、content 等阶段。这意味着：
- 此时请求 URI 已解析完毕，但尚未匹配到具体 location 或转发给 upstream
- 你可以安全读取并修改 ngx.var.uri、ngx.var.args、ngx.var.request_uri 等变量
- 修改后的 URI 会参与后续的 location 匹配，相当于“重放”一次路由决策
- 不能直接返回响应体（如用 ngx.say），但可用 ngx.redirect 或 ngx.exit 终止流程
常见实用场景与写法
以下操作均在 location 块内通过 rewrite_by_lua_block 或 rewrite_by_lua_file 实现：
-
动态补全路径：把
/user/123改为/api/v2/users?id=123 -
按参数分流：当
arg_env=staging时，将请求改写到/internal-staging$uri -
静态资源自动加版本前缀：把
/css/app.css改为/v202605/css/app.css（配合缓存策略） - IP 白名单透传：检测 ngx.var.remote_addr，命中则设置 ngx.var.upstream_name = "new_backend"，供后续 proxy_pass 使用
必须注意的限制与陷阱
rewrite_by_lua 能力强大，但有明确边界，误用易引发不可预期行为：
- 不是所有 Nginx 变量都可写，例如 ngx.var.host 可读不可写，强行赋值无效
- 修改 ngx.var.uri 后，原 ngx.var.request_uri 不会同步更新（它是原始未解码字符串）
- 若在 rewrite_by_lua 中调用阻塞式 I/O（如同步 Redis 查询），会卡住整个 worker 进程，务必使用 lua-resty-redis 的 cosocket 异步接口
- 错误未捕获会导致 500 响应，建议包裹 pcall：
local ok, err = pcall(function() ... end)
if not ok then ngx.log(ngx.ERR, "rewrite failed: ", err) ngx.exit(500) end
一个轻量灰度路由示例
将 /api 下部分请求按百分比导向新服务：
location /api/ {
rewrite_by_lua_block {
local uri = ngx.var.uri
local percent = 10 -- 10% 流量走新路径
local rand = math.random(100)
<pre class="brush:php;toolbar:false;"> if rand <= percent and string.match(uri, "^/api/(user|order)") then
ngx.var.uri = "/new-api" .. uri
return
end
}
proxy_pass http://legacy_upstream;}
该配置无需重启、不增加额外组件，上线即生效，适合快速验证新接口兼容性。
