proxy_set_header仅原样注入字符串，不解析复杂参数；json、url编码等需依赖变量拼接、map模块或lua模块实现，后端负责最终解析。

在 Nginx 中，proxy_set_header 本身不处理“复杂参数”的解析或构造，它只是把指定的字符串值原样注入到转发给后端的 HTTP 请求头中。所谓“复杂参数”，比如 JSON 对象、带空格/特殊字符的字符串、多值数组、动态拼接的路径等，关键在于你如何在 Nginx 配置里生成这个字符串——Nginx 原生不支持 JSON 编码、URL 编码或数组序列化，需靠变量组合、内置变量、map 模块或第三方模块（如 nginx-module-lua）来实现。

用变量拼接构造含特殊字符的 header 值

Nginx 变量可嵌套引用，配合 map 或 set（需 ngx_http_rewrite_module）能组装较复杂的字符串：

• 直接拼接：例如传递用户来源 + 时间戳：proxy_set_header X-Request-Info "$remote_addr|$time_iso8601";
• 避免空格截断：用引号包裹整个值（Nginx 会保留引号并传给后端），如：proxy_set_header X-Meta-Data '"{""user"":""$remote_user"",""path"":""$request_uri""}"'; —— 注意内部双引号要转义为 ""（JSON 字符串内），且整个值用单引号包裹
• 对特殊字符做简单转义：Nginx 不自动 URL 编码，若需传递含空格、斜杠等的参数，建议后端负责解码；或用 Lua 模块调用 ngx.escape_uri() 处理

用 map 模块实现条件化 header 注入

当 header 值需根据请求特征（如 host、path、query）动态选择时，map 比 if 更安全高效：

FastAPI Flask Proxy

FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。

下载

• 定义映射关系（写在 http 块中）：

  map $arg_env $backend_env {<br>  default "prod";<br>  "dev"   "development";<br>  "test"  "staging";<br>}

• 在 location 中使用：proxy_set_header X-Env-Type $backend_env;
• 支持正则和嵌套 map，但不能直接生成 JSON；如需结构化数据，仍需拼接字符串

用 Lua 模块处理真正复杂的逻辑

若需序列化 table、调用函数、处理数组或做 Base64 编码等，推荐 nginx-module-lua：

• 安装后，在 location 中执行 Lua：

  access_by_lua_block {<br>  local cjson = require "cjson"<br>  local data = {<br>    ip = ngx.var.remote_addr,<br>    ua = ngx.var.http_user_agent,<br>    ts = ngx.time()<br>  }<br>  ngx.req.set_header("X-Payload", cjson.encode(data))<br>}

• 注意：Lua 设置的 header 在 proxy_set_header 之后仍有效，会被最终发往后端
• 相比纯配置，Lua 灵活度高，但增加运维复杂度和性能开销，简单场景不建议过度使用

后端接收时的关键提醒

无论 header 值多复杂，Nginx 只负责“传递字符串”。后端能否正确解析，取决于双方约定：

• JSON 字符串需确保双引号、转义符合法，推荐用 Lua 的 cjson.encode 而非手动拼接
• 多值参数（如权限列表）可传逗号分隔字符串，或用多个同名 header（Nginx 默认覆盖，需用 proxy_pass_request_headers off + 自定义逻辑控制）
• 避免 header 值过长或含非法字符（如控制字符、未编码的换行），可能被后端拒绝或截断