在 nginx 中追加查询参数,最稳妥的方式是使用 map 模块结合 rewrite 指令。通过定义一个映射规则,将原始 uri 与追加后的 uri 关联起来,并在 location 块中应用该规则,即可实现参数的透明追加。

如何配置基础的重写逻辑
使用 map 指令可以创建一个变量映射表,指定当请求的 URI 匹配特定模式时,目标 URI 应包含哪些新参数。这种方法避免了复杂的正则表达式捕获组,使配置更易于维护。

http {
# 定义映射:如果 URI 以 /api/ 开头
map $uri $new_uri {
~^/api/(.*)$ /api/$1?source=nginx_rewrite;
default $uri;
}
server {
listen 80;
server_name example.com;
location / {
# 执行重写
rewrite ^ $new_uri last;
# 后续处理...
proxy_pass http://backend;
}
}
}
上述配置中,map 块定义了 $new_uri 的值。如果请求路径是 /api/data,它将被重写为 /api/data?source=nginx_rewrite。last 标志告诉 Nginx 停止处理当前的 rewrite 规则集,并使用新的 URI 重新开始匹配过程。
如何处理多个参数的追加
当需要追加多个参数或基于条件动态生成参数时,可以在 map 中使用更复杂的逻辑,或者直接在 location 中使用 if 语句配合 $args 变量。但推荐使用 map 以保持配置的声明式特性。

http {
map $uri $append_params {
# 追加单个参数
~^/v1/(.*)$ ?version=v1&format=json;
# 追加多个参数
~^/v2/(.*)$ ?version=v2&format=json&debug=true;
default '';
}
server {
listen 80;
server_name example.com;
location / {
# 检查是否需要追加参数
if ($append_params != '') {
# 将原始 URI 与新参数组合
rewrite ^ $uri$append_params last;
}
proxy_pass http://backend;
}
}
}
在这个例子中,map 根据 URI 的前缀决定追加哪些参数。如果匹配到 /v1/,则追加 ?version=v1&format=json。如果匹配到 /v2/,则追加更多参数。这种结构清晰且易于扩展。
当原始 URI 已包含查询参数时如何处理
如果原始 URI 已经包含查询参数(例如 /api/data?id=123),直接追加新参数会导致冲突或格式错误。Nginx 的 map 和 rewrite 不会自动处理 & 分隔符,因此需要手动拼接或使用更高级的技巧。
http {
map $uri $final_uri {
# 假设我们想追加 source=nginx
# 注意:这里没有自动处理 & 的逻辑
~^/api/(.*)$ /api/$1?source=nginx;
default $uri;
}
server {
listen 80;
server_name example.com;
location / {
# 获取原始查询字符串
set $original_args $query_string;
# 执行重写
rewrite ^ $final_uri last;
# 在 proxy_pass 之前,我们可以重新构建查询字符串
# 但这通常需要在后端处理或使用 Lua
proxy_pass http://backend;
}
}
}
对于这种情况,最简单的解决方案是在后端应用中处理参数合并。如果必须在 Nginx 层处理,可以使用 set 指令和 if 来手动拼接 &,但这会使配置变得复杂且难以维护。另一种方法是使用 proxy_set_header 将原始查询字符串传递给后端,由后端负责合并。











