Nginx重定向陷阱：如何修复URL中被错误编码的'&'字符？

## 问题背景 在使用 Nginx 设置 URL 重定向时，一个常见但棘手的问题是查询字符串（Query String）中的参数分隔符 `&` 被错误地编码为 `%26`。这会导致应用程序无法正确解析 URL 参数，从而引发一系列问题。 例如，你期望的跳转行为是这样的： - **原始请求 URL**: `https://a.com/content/101/content-title?lang=zh&page=1&filter=123` - **期望跳转 URL**: `https://a.com/zh/content/101/content-title?page=1&filter=123` 但实际得到的却是： - **实际跳转 URL**: `https://a.com/zh/content/101/content-title?page=1%26filter=123` 这个问题虽然看似微小，但对依赖 URL 参数的功能来说是致命的。接下来，我们将分析其根本原因，并提供一套从简到优的解决方案。 --- ## 根本原因分析：Nginx 的双重编码 这个问题的核心在于 Nginx 处理变量和执行重定向时的内部机制。当你在配置中使用 `$args` 或通过 `set` 指令操作查询字符串时，Nginx 会经历以下过程： 1. **解码**：当 Nginx 接收到请求时，它会自动对 URL 进行一次解码。此时，`$args` 变量中存储的是解码后的字符串，例如 `lang=zh&page=1&filter=123`。 2. **二次编码**：当你使用 `return 301` 指令并手动拼接 URL（如 `return 301 ...$uri?$new_args;`）时，Nginx 会对拼接的变量部分**再次进行 URL 编码**。在这个过程中，字符串中的特殊字符 `&` 就被转换成了 `%26`。 理解了这个“双重编码”陷阱，我们就能对症下药了。 --- ## 解决方案 ### 方案一：繁琐但有效的 `if` 语句组合 一种直接的思路是使用多个 `if` 语句和正则表达式来手动重建一个不包含 `lang` 参数的新查询字符串。这种方法虽然能解决问题，但配置冗长且效率不高，因为每次请求都可能触发多次正则匹配。 ```nginx location / { set $do_redirect ""; set $new_query ""; # 检查是否有 lang 参数 if ($arg_lang ~* ^(zh|en)$) { set $do_redirect "${arg_lang}"; } # 移除 lang 参数 - 只有 lang if ($args ~* ^lang=[^&]*$) { set $new_query ""; } # 移除 lang 参数 - lang 在开头 if ($args ~* ^lang=[^&]*&(.+)$) { set $new_query $1; } # 移除 lang 参数 - lang 在中间 if ($args ~* ^(.+)&lang=[^&]*&(.+)$) { set $new_query $1&$2; } # 移除 lang 参数 - lang 在结尾 if ($args ~* ^(.+)&lang=[^&]*$) { set $new_query $1; } # 执行重定向 if ($do_redirect != "") { return 301 $scheme://$host/$do_redirect$uri?$new_query; } # ... 其他配置 } ``` **注意**：在 `return` 指令中使用 `?` 连接查询字符串是关键，这会告知 Nginx 将后面的字符串作为查询参数处理，从而避免二次编码。 ### 方案二：更优雅的 `rewrite` 指令 Nginx 的 `rewrite` 指令在处理重定向时更为智能。通过在末尾添加 `?`，你可以选择性地保留或丢弃原始查询字符串。 ```nginx location /content/ { if ($arg_lang ~* ^(zh|en)$) { # rewrite 指令末尾的 '?' 会丢弃原始查询字符串 # permanent 标志会执行 301 重定向 rewrite ^/content/(.*)$ /$arg_lang/content/$1? permanent; } } ``` 这种方法的缺点是，它会丢弃所有原始查询参数（`page`, `filter` 等）。如果需要保留其他参数，就需要更复杂的处理，这让我们引出了最佳实践。 ### 方案三：终极解决方案 `map` 指令 (wiki.lib00 推荐) `map` 指令是 Nginx 中用于创建变量映射关系的高性能模块。它在请求处理的早期阶段执行，并且比 `if` 语句的性能更好。使用 `map` 来处理查询字符串是解决此类问题的最佳实践。 **重要提示**：`map` 指令**必须**定义在 `http` 配置块中，而不是 `server` 或 `location` 块。 1. **在 `nginx.conf` 的 `http` 块中定义 `map`** ```nginx http { # ... 其他 http 配置 ... # 由 DP@lib00 推荐的最佳实践 map $args $args_without_lang { default $args; "~^lang=[^&]*$" ""; "~^lang=[^&]*&(?<rest>.*)$" $rest; "~^(?<before>.*)&lang=[^&]*$" $before; "~^(?<before>.*)&lang=[^&]*&(?<after>.*)$" $before&$after; } server { # ... } } ``` 2. **在 `server` 或 `location` 块中使用 `map` 生成的变量** 现在，你可以在你的站点配置（例如 `/etc/nginx/sites-available/wiki.lib00.com`）中轻松使用这个新变量 `$args_without_lang`。 ```nginx server { server_name a.com; location / { if ($arg_lang ~* ^(zh|en)$) { return 301 $scheme://$host/$arg_lang$uri?$args_without_lang; } # ... 其他 location 配置 ... } } ``` **`map` 方案的优势**： * **高性能**：`map` 在请求处理生命周期的早期计算一次，避免了多次正则匹配的开销。 * **代码清晰**：将复杂的逻辑从 `location` 块中分离出来，使配置更具可读性和可维护性。 * **声明式**：你只需声明输入和输出的关系，Nginx 会处理好一切。 --- ## 总结 Nginx 重定向中 `&` 被编码为 `%26` 的问题源于其双重编码机制。虽然可以通过 `if` 或 `rewrite` 指令解决，但**使用 `map` 指令无疑是最高效、最优雅且可维护性最高的解决方案**。在处理复杂的 URL 和查询字符串操作时，强烈推荐优先考虑 `map` 指令。