Nginx中proxy_pass含URI时会丢弃原始查询字符串，正确做法是proxy_pass仅写上游地址（如http://backend）或用$request_uri拼接，确保?q=xxx等参数完整透传。
在 Nginx 中使用 proxy_pass 时，如果上游 URL 包含问号（?）和动态参数，Nginx 默认会自动截断并重写查询字符串，导致参数丢失或重复。这不是 bug，而是设计行为——关键在于理解 Nginx 如何处理 URI 和 query string 的传递逻辑。
理解 Nginx 对 query string 的默认行为
当 proxy_pass 指令的值包含 URI（即带路径，如 http://backend/api/），Nginx 会丢弃原始请求的 URI 路径部分，并重新拼接查询字符串；而如果 proxy_pass 值不带 URI（仅主机端口，如 http://backend），则完整保留客户端请求的 URI（含 path + query string）。
常见错误写法：
location /search {
proxy_pass http://backend/search?from=nginx; # ❌ 错误：会丢弃原始 ?q=xxx
}这样写会导致客户端传来的 ?q=nginx 被丢弃，只留下 ?from=nginx。
正确传递原始 query string 的方法
要确保原始问号后的参数（如 /search?q=nginx&page=2）完整透传给后端，推荐以下方式：
- 避免在 proxy_pass 后硬编码 URI 路径：改用不带路径的 upstream 或变量拼接
- 用 $request_uri 史上最稳妥的方式：它原样包含 path + query string
- 需要追加固定参数时，用 $args 或 $query_string 配合 rewrite
示例（推荐）：
location /search {
proxy_pass http://backend; # ✅ 不带路径，自动透传 /search?q=...
}若需在透传基础上额外添加参数（如打标 &via=nginx），可用：
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
location /search {
proxy_pass http://backend;
proxy_set_header X-Original-URI $request_uri;
# 利用 rewrite 拼接（注意 flag break 防循环）
rewrite ^(.*)$ $1?via=nginx&$args break;
}或者更清晰地用 proxy_redirect off + proxy_pass 变量（Nginx ≥ 1.13.10）：
location /search {
set $backend_url "http://backend$request_uri";
proxy_pass $backend_url; # ✅ 完整拼接，含原始 ? 参数
}需要重写 query string 的场景（如过滤、改写）
若需修改参数（例如把 ?q=xxx 改成 ?keyword=xxx），不能依赖 proxy_pass 自动处理，应主动解析：
- 用
map提取并映射参数值（适合简单替换） - 用
rewrite+break重写整个 URI（推荐） - 后端服务配合处理更灵活，Nginx 层尽量保持轻量
示例：将 /search?q=xxx → 透传为 /api/v1/search?term=xxx
location /search {
if ($args ~* "^q=(.+)$") {
set $q_val $1;
rewrite ^/search$ /api/v1/search?term=$q_val break;
}
proxy_pass http://backend;
}注意：if 在 location 中可用，但避免嵌套复杂逻辑；生产环境建议用 map 提前解析。
调试技巧：确认参数是否到达后端
遇到参数异常，优先验证两点：
- 在 Nginx 日志中记录
$request_uri和$args，确认进站时参数完整 - 在后端打印原始请求 URL 或 header（如
X-Original-URI），排除 Nginx 截断 - 用
curl -v对比 Nginx 入口和直连后端的响应差异
日志配置参考：
log_format debug '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent" '
'req_uri:"$request_uri" args:"$args"';核心就一条：让 proxy_pass 不参与 URI 构造，交由 $request_uri 或显式 rewrite 控制，就能稳稳处理带问号的动态参数。
