Nginx rewrite重定向参数过滤方法：选择性保留和剔除查询参数的实战配置

# Nginx rewrite重定向参数过滤方法：选择性保留和剔除查询参数的实战配置

在Nginx重定向配置中，我们经常遇到需要过滤查询参数的场景：保留有用的UTM追踪参数，剔除无用的跟踪参数，或者只传递部分必要参数。本文将详细介绍Nginx rewrite重定向中参数过滤的多种方法，让你能够精确控制查询参数的传递。

## 为什么需要参数过滤？

在实际网站运营中，URL中的查询参数可能包含：

1. 有用参数：utm_source、utm_medium、utm_campaign等流量追踪参数
2. 无用参数：fbclid（Facebook点击ID）、gclid（Google点击ID）等平台跟踪参数
3. 会话参数：sessionid、jsessionid等会话标识
4. 分页参数：page、limit等分页控制参数

不合理的参数传递会导致：
- 缓存效率降低（相同内容被缓存多次）
- 统计数据污染（同一页面被统计为多个URL）
- SEO问题（重复内容被判定为不同页面）
- 隐私泄露（会话ID出现在日志中）

## 方法一：使用rewrite问号清空所有参数

最简单的参数过滤方法是使用rewrite的问号语法清空所有参数，然后重新添加需要的参数。

### 基本语法

``nginx
# 清空所有参数，只保留指定参数
rewrite ^/old-page$ /new-page?utm_source=$arg_utm_source&utm_medium=$arg_utm_medium? last;
`

关键点：
- rewrite替换字符串中的?会清空原始查询参数
- 然后你可以手动添加需要的参数
- 使用$arg_参数名获取原始请求中的特定参数值

### 完整示例

`nginx
# 只保留utm_source和utm_medium参数
location = /product {
rewrite ^ /product-new?utm_source=$arg_utm_source&utm_medium=$arg_utm_medium? last;
}

# 后续处理
location = /product-new {
# 这里接收到的参数是过滤后的
# 原始: /product?utm_source=google&utm_medium=cpc&fbclid=123
# 过滤后: /product-new?utm_source=google&utm_medium=cpc
}
`

## 方法二：使用map指令过滤参数

对于复杂的参数过滤需求，使用map指令更加灵活和高效。

#### 1. 创建参数过滤映射

`nginx
http {
# 定义需要保留的参数白名单
map $args $filtered_args {
default "";
"~(.)(utm_source=[^&])(.*)" "$2";
"~(.)(utm_medium=[^&])(.*)" "$1$2$3";
# 更多参数匹配规则...
}

# 或者使用更灵活的方式
map $arg_utm_source $keep_utm_source {
"" "";
default "utm_source=$arg_utm_source";
}

map $arg_utm_medium $keep_utm_medium {
"" "";
default "&utm_medium=$arg_utm_medium";
}

# 组合过滤后的参数
set $final_args "$keep_utm_source$keep_utm_medium";
}
`

#### 2. 在rewrite中使用过滤后的参数

`nginx
location /campaign {
# 使用过滤后的参数
rewrite ^ /new-campaign?$final_args? last;
}
`

### 更简单的map方案

`nginx
http {
# 定义参数过滤规则
map $args $clean_args {
# 只保留utm_source和utm_medium
"~(.)(utm_source=[^&])(.*)" "$2";
"~(.)(utm_medium=[^&])(.*)" "$1$3";
default "";
}

# 或者直接使用正则表达式提取
map $args $keep_args {
"~(utm_source=[^&]|utm_medium=[^&])" "$1";
default "";
}
}
`

## 方法三：使用if条件判断过滤

虽然Nginx不推荐在if中使用rewrite，但对于简单的参数过滤场景，if条件判断仍然有效。

`nginx
location /promo {
# 只保留特定参数
if ($args ~ "(utm_source=[^&]|utm_medium=[^&])") {
set $clean_args $1;
rewrite ^ /promo-new?$clean_args? last;
}

# 如果没有需要的参数，直接重定向
rewrite ^ /promo-new? last;
}
`

注意：if指令在Nginx中有一些奇怪的行为，建议先在测试环境验证。

## 方法四：使用return指令精确控制

相比rewrite，return指令在参数过滤方面更加直观和高效。

`nginx
location /landing {
# 只保留utm_source参数
if ($arg_utm_source) {
return 301 /landing-new?utm_source=$arg_utm_source;
}

# 没有参数或不需要的参数，直接跳转
return 301 /landing-new;
}
`

### 使用return 307保留POST参数

`nginx
location /api/submit {
# 只保留api_key参数，其他参数丢弃
if ($arg_api_key) {
return 307 /api/submit-new?api_key=$arg_api_key;
}
return 307 /api/submit-new;
}
`

## 方法五：使用proxy_pass_request_args控制代理参数

当Nginx作为反向代理时，可以使用proxy_pass_request_args指令控制是否传递查询参数。

`nginx
location /backend {
# 不传递任何查询参数给后端
proxy_pass_request_args off;
proxy_pass http://backend-server;
}

location /backend-with-filter {
# 只传递过滤后的参数
set $backend_args "user=$arg_user&token=$arg_token";
proxy_pass_request_args off;
proxy_pass http://backend-server?$backend_args;
}
`

## 实战案例：UTM参数保留+垃圾参数过滤

### 需求描述
- 保留：utm_source、utm_medium、utm_campaign
- 剔除：fbclid、gclid、_ga等平台跟踪参数
- 重定向到新URL结构

### 解决方案

`nginx
http {
# 定义UTM参数提取
map $arg_utm_source $has_utm_source {
"" "";
default "utm_source=$arg_utm_source";
}

map $arg_utm_medium $has_utm_medium {
"" "";
default "&utm_medium=$arg_utm_medium";
}

map $arg_utm_campaign $has_utm_campaign {
"" "";
default "&utm_campaign=$arg_utm_campaign";
}

# 组合最终参数
set $utm_params "$has_utm_source$has_utm_medium$has_utm_campaign";
}

server {
location /old-tracking {
# 使用return 301重定向并只保留UTM参数
if ($utm_params) {
return 301 /new-tracking?$utm_params;
}
return 301 /new-tracking;
}
}
`

## 性能对比：rewrite vs return vs map

| 方法 | 性能 | 灵活性 | 推荐场景 |
|------|------|--------|----------|
| rewrite问号清空 | 中 | 低 | 简单参数替换 |
| map指令过滤 | 高 | 高 | 复杂参数过滤 |
| if条件判断 | 低 | 中 | 简单条件过滤 |
| return指令 | 高 | 中 | 精确参数控制 |
| proxy_pass_request_args | 高 | 低 | 代理场景参数控制 |

## 调试技巧：查看过滤后的参数

### 1. 使用add_header调试

`nginx
location /debug {
add_header X-Original-Args "$args";
add_header X-Filtered-Args "$filtered_args";
# 实际配置...
}
`

### 2. 使用echo模块调试

`nginx
location /debug {
echo "Original args: $args";
echo "Filtered args: $filtered_args";
echo "UTM source: $arg_utm_source";
}
`

### 3. 使用log_format记录

`nginx
http {
log_format filter_log '$remote_addr - $args - $filtered_args';
access_log /var/log/nginx/filter.log filter_log;
}
`

## 常见问题与解决方法

### 问题1：参数过滤后页面404
原因：过滤后的参数不完整，导致后端无法处理请求
解决：确保保留所有必要参数，或使用默认值

### 问题2：循环重定向
原因：过滤规则导致URL不断变化，形成重定向循环
解决：使用rewrite_log on;调试，检查重定向链

### 问题3：中文参数乱码
原因：Nginx默认使用UTF-8编码，但某些应用使用GBK
解决：在proxy_pass中显式指定字符集

## 最佳实践建议

1. 优先使用return指令：性能更好，行为更可预测
2. 复杂过滤用map：灵活且高效，适合生产环境
3. 避免过度过滤：保留必要的功能参数
4. 测试重定向链：使用curl -L`检查重定向是否循环
5. 监控过滤效果：定期检查日志，确保参数过滤符合预期

## 总结

Nginx rewrite参数过滤是网站运维中的常见需求，通过rewrite问号语法、map指令、if条件判断、return指令等多种方法，我们可以精确控制查询参数的传递。对于简单场景，使用rewrite或return即可；对于复杂过滤需求，map指令是最佳选择。

在实际应用中，建议根据性能需求、灵活性要求和团队熟悉程度选择合适的方法。无论选择哪种方法，都要记得测试重定向行为，避免循环重定向和参数丢失问题。

## 相关文章

- [Nginx rewrite保留查询参数完整教程](https://www.youres.cn/blog/1025) - 基础参数保留方法
- [Nginx return 301 保留参数配置方法](https://www.youres.cn/blog/1127) - return指令参数处理
- [Nginx $is_args和$args组合用法详解](https://www.youres.cn/blog/1066) - 参数拼接技巧
- [Nginx rewrite问号含义解析](https://www.youres.cn/blog/1079) - 问号语法深度解析

---
本文详细介绍了Nginx rewrite重定向中参数过滤的5种方法，从简单到复杂，从基础到实战，帮助你掌握查询参数精确控制的技巧。