set_escape_uri 并非 Nginx 官方指令，实际不存在；URI 编码需依赖 set-misc-nginx-module 提供的 set_encode_uri 或 set_encode_uri_args 指令，分别用于路径片段和查询参数的标准化编码。
set_escape_uri 并不是 Nginx 官方指令，它并不存在于标准 Nginx 模块中。Nginx 本身没有名为 set_escape_uri 的内置指令 —— 这个名字容易让人误以为是类似 set（来自 set-misc-nginx-module）的扩展指令，但实际并不存在一个叫 set_escape_uri 的功能。
真正可用的 URI 编码方式：使用 set-misc 模块的 set_encode_uri / set_encode_uri_args
如果你需要对变量内容做 URI 编码（即 percent-encoding，如空格 → %20），需借助第三方模块 set-misc-nginx-module（常与 OpenResty 一起提供）。该模块提供了：
-
set_encode_uri $encoded_value $original_value;—— 对整个字符串做 URI 编码（不编码/、.等路径安全字符，符合 RFC 3986 的“unreserved”规则） -
set_encode_uri_args $encoded_args $args;—— 专门用于编码 query string 参数值（更严格，会编码更多字符）
注意：set_encode_uri 不会对 /、:、@ 等字符编码，适合编码路径片段；若需完全编码（如作为 URL 查询参数值），应优先用 set_encode_uri_args 或手动组合。
代理请求头中传递编码后变量的典型写法
假设你想把原始请求头 X-User-Name 的值 URI 编码后，作为新请求头 X-Encoded-Name 透传给上游：
location /api/ {
# 加载 set-misc 模块后才可用
set_encode_uri_args $encoded_name $http_x_user_name;
<pre class="brush:php;toolbar:false;">proxy_set_header X-Encoded-Name $encoded_name;
proxy_pass https://backend/;}
⚠️ 注意事项：
-
$http_x_user_name是自动映射的请求头变量（小写 + 下划线），Nginx 默认将请求头转为小写并替换-为_ - set_encode_uri* 必须在
proxy_set_header之前执行 - $http_x_user_name 为空字符串，
set_encode_uri_args会输出空字符串（不会报错）
纯 Nginx（无第三方模块）的替代方案
如果不安装 set-misc 模块，Nginx 原生无法对任意变量做 URI 编码。常见折中做法包括：
- 由客户端确保传递已编码的值（如前端调用
encodeURIComponent()后设 header） - 在 upstream（如 Node.js/Python 服务）中解码，避免在 Nginx 层处理
- 用 Lua（OpenResty）：通过
ngx.escape_uri()精确控制编码逻辑
例如 OpenResty 中：
rewrite_by_lua_block {
local name = ngx.var.http_x_user_name or ""
ngx.var.encoded_name = ngx.escape_uri(name)
}
再通过 proxy_set_header X-Encoded-Name $encoded_name; 透传。
为什么不能直接用 map + regex 模拟编码？
有人尝试用 map 配合正则替换实现简单编码（如把空格替成 %20），但这种方式：
- 无法覆盖所有需编码字符（如
中文、€、+、#等） - 易出错且不可靠（URL 编码需 UTF-8 字节序列 + 十六进制转义）
- Nginx 的
map不支持动态多轮替换，无法正确处理 Unicode
因此不推荐自行实现，应依赖成熟模块或后端处理。
