排查 nginx rewrite 后参数丢失，核心在于确认请求 uri 中的查询字符串（query string）是否被自动保留。nginx 的 rewrite 指令默认会保留原始请求的 ?key=value 部分，但如果重写规则中显式指定了新的 uri 且未包含 $args 或 $query_string，或者使用了 break、last 等标志导致后续处理逻辑变化，参数可能会在内部重定向或代理转发时丢失。要解决这个问题，需检查重写规则是否显式拼接了参数变量，并确认 proxy_pass 或 fastcgi_pass 的目标地址格式是否正确。
为什么 rewrite 后的 URL 没有携带原参数？
当使用 rewrite 指令进行 URL 重写时，如果目标 URI 是绝对路径或相对路径但未显式附加参数，Nginx 的行为取决于是否使用了特定的标志位以及后续的处理器配置。默认情况下，Nginx 会自动将原始查询字符串附加到重写后的 URI 上，除非你明确告诉它不要这样做，或者在重写表达式中包含了特殊字符导致解析中断。最常见的情况是，开发者在重写规则中手动构建了新路径，却忘记了追加 $args，或者错误地使用了 redirect 标志导致浏览器端重新发起请求时参数编码异常。
server {
listen 80;
server_name example.com;
# 场景：重写 /old 到 /new，但参数丢失
location /old {
# 错误写法：只重写路径，未显式保留 args（虽然默认会保留，但在某些复杂正则或 break 下可能失效）
rewrite ^/old/(.*)$ /new/$1 last;
}
# 正确写法：显式保留参数，确保万无一失
location /new {
# 这里可以访问 $args 来调试
default_type text/plain;
return 200 "Path: $uri\nArgs: $args";
}
}
在上述配置中，访问 /old/test?foo=bar 时，Nginx 会将请求内部重定向到 /new/test，并自动附加 ?foo=bar。最终 /new 位置块接收到的 $uri 为 /new/test，$args 为 foo=bar。如果希望完全控制参数传递，可以在 rewrite 目标中显式添加 ?$args，例如 rewrite ^/old/(.*)$ /new/$1?$args last;。此外，若使用 return 指令代替 rewrite，则不会自动附加参数，必须手动拼接 $args。
proxy_pass 重写后参数为何消失？
当 Nginx 作为反向代理使用时，proxy_pass 指令的目标地址格式决定了查询字符串的处理方式。如果 proxy_pass 指向的是一个不带 URI 的域名或 IP，Nginx 会将客户端原始的完整 URI（包括查询字符串）原样传递给后端服务器。然而，如果 proxy_pass 指向的是一个带有 URI 的路径，Nginx 会用该路径替换客户端请求中的匹配部分，而查询字符串的处理则依赖于是否显式指定了 $args 或 $query_string。许多开发者误以为 proxy_pass 会自动保留参数，实际上在某些重写组合下，参数会被截断或覆盖。
server {
listen 80;
server_name example.com;
location /api/ {
# 错误写法：proxy_pass 带 URI，但未处理 args
# 假设请求为 /api/users?id=1
# Nginx 会将 /api/users 替换为 http://backend/v1/users
# 但 ?id=1 可能丢失，取决于具体版本和配置
proxy_pass http://backend/v1/;
}
# 正确写法：显式传递 args
location /api/ {
proxy_pass http://backend/v1/?$args;
# 或者使用 $is_args 和 $args 组合
# proxy_pass http://backend/v1/$is_args$args;
}
}
在第一个示例中，请求 /api/users?id=1 被代理到 http://backend/v1/users，但 ?id=1 可能未被正确传递，因为 proxy_pass 中的 URI 部分 /v1/ 替换了 /api/，而查询字符串的处理变得不确定。在第二个示例中，通过在 proxy_pass 末尾添加 ?$args，确保了原始查询字符串被显式附加到后端请求中。这是解决参数丢失的关键步骤。此外，若后端服务需要不同的参数格式，可以使用 set 指令预处理 $args，再进行传递。
如何验证 rewrite 后参数是否成功传递到后端？
为了验证参数是否成功传递，最直接的方法是在 Nginx 配置中添加日志记录或使用一个简单的后端服务打印接收到的参数。通过检查 Nginx 的错误日志或访问日志，可以确认 $args 变量的值是否在重写前后保持一致。此外，可以使用 curl 工具模拟请求，观察响应头或响应体中是否包含预期的参数信息。这种方法有助于快速定位参数丢失的具体环节，是排查此类问题的标准实践。
