nginx转发含特殊字符的自定义请求头时只透传不编解码，静态值须用单引号包裹防解析错误，变量值需确保非空且洁净，原生不支持base64/url编码，验证应以后端原始字节为准。
带特殊字符（如空格、引号、斜杠、非 ASCII 字符）的自定义请求头，在 Nginx 中转发时不会自动报错，但需注意值的书写方式、变量来源可靠性以及后端能否正确解析——Nginx 本身只做透传，不负责编码或转义。
静态值中含空格或引号：用单引号包裹整个值
Nginx 配置解析器对双引号内的内容较敏感（尤其当值里含 `$` 或 shell 类符号时），虽不经过 shell 执行，但为避免歧义和未来兼容性风险，推荐统一用单引号：
-
✅ 推荐写法：
proxy_set_header X-Api-Token 'Bearer eyJhbGciOi...'; -
⚠️ 慎用写法：
proxy_set_header X-Api-Token "Bearer eyJhbGciOi...";（若 token 含 `$` 可能被误解析为变量） -
❌ 错误写法：
proxy_set_header X-Api-Token Bearer eyJhbGciOi...;（空格导致语法错误，Nginx 启动失败）
变量值含特殊字符：确保变量有定义且内容干净
当使用 $http_x_api_token 等变量透传客户端头时，Nginx 会原样转发其原始字节。但要注意：
- 若客户端未发送该头，
$http_x_api_token为空字符串，后端可能因收到空值而校验失败 - 若客户端发送了 URL 编码后的值（如
X-Api-Token: %7B%22id%22%3A1%7D），Nginx 不解码，直接透传；后端需自行 decode - 建议在
map块中做简单过滤，例如剔除明显非法字符：map $http_x_api_token $safe_token {<br> ~^[a-zA-Z0-9_\-\.=+\/]+[=]*$ $http_x_api_token;<br> default ""; }
再用proxy_set_header X-Api-Token $safe_token;
需要 Base64 或 URL 编码？Nginx 原生不支持，得靠扩展或前置服务
纯 Nginx（无第三方模块）无法对 header 值做 Base64 编码、URL encode 或哈希计算。常见应对方式：
- 前端或网关层提前生成并携带已编码的头（最轻量）
- 引入
ngx_http_lua_module，用 Lua 脚本处理：set_by_lua_block $encoded { return ngx.escape_uri(ngx.var.http_x_raw_data) }proxy_set_header X-Encoded-Data $encoded; - 用 OpenResty 或 Envoy 做更复杂的头加工，Nginx 仅作流量入口
验证是否透传成功：看后端收到的原始字节
最可靠的方式是让后端打印接收到的完整请求头（包括原始字节序列）。例如 Node.js 中：
-
console.log('Raw headers:', req.rawHeaders);（保留大小写和原始空格） - 对比 Nginx 日志中
$http_x_api_token的值（需开启log_format自定义字段） - 避免只查
req.headers['x-api-token']—— 某些框架会自动 trim 或 normalize，掩盖问题
