一、初识rewrite规则的应用场景

作为Web服务器领域的瑞士军刀，Nginx的rewrite模块承担着流量调度的重要职责。在以下典型场景中我们经常需要它：

  1. 网站改版时需要保持旧URL可访问（如/product?id=123 → /products/123）
  2. 实现伪静态化提升SEO效果（如.php路径转为.html）
  3. 多域名统一规范化（将www和非www域名统一）
  4. 灰度发布时的流量切分（按设备类型重定向到不同后端）

某电商平台的真实案例：当商品详情页URL结构调整时，技术团队通过rewrite规则将旧格式的千万级URL自动映射到新路径，保证搜索引擎权重不流失且用户无感知。

二、rewrite规则失效的五大常见原因

2.1 配置位置错误

错误示例：

server {
    location /api {
        proxy_pass http://backend;
    }
    
    # 错误的放置位置（在location块之外）
    rewrite ^/v1/(.*)$ /v2/$1 permanent;
}

正确配置：

server {
    # 全局重写规则应放在server块顶部
    rewrite ^/v1/(.*)$ /v2/$1 permanent;

    location /api {
        # 特定路径的重写规则
        rewrite ^/api/(v1)/(.*)$ /$1/$2 break;
        proxy_pass http://backend;
    }
}

▶ 原理说明：server级的rewrite会优先于location匹配执行，不当的放置位置可能导致规则被跳过

2.2 正则表达式陷阱

典型错误案例：

# 试图匹配所有.html路径去掉扩展名
rewrite ^(.*)\.html$ $1 permanent;

问题分析：当访问/news.html?page=2时，原始URI不包含查询参数，正确写法应为：

rewrite ^(.*)\.html$ $1 permanent;

但实际应使用$request_uri：

if ($request_uri ~ "^/(.*)\.html(\?.*)?$") {
    rewrite ^/(.*)\.html$ /$1 permanent;
}

▶ 技术要点：理解$uri与$request_uri的区别，正确处理查询参数

2.3 flag标志使用不当

对比实验：

# 案例A（错误）
location /shop {
    rewrite ^/shop/(\d+)$ /product?id=$1;
}

# 案例B（正确）
location /shop {
    rewrite ^/shop/(\d+)$ /product?id=$1 last;
}

差异说明：未指定flag时默认使用last，但在某些上下文环境中可能导致中断。建议显式声明break/last/redirect等标志。

2.4 配置加载顺序问题

优先级示例：

server {
    rewrite ^/old/(.*) /new/$1 permanent;  # 规则A
    
    location /old {
        rewrite ^/old/(.*) /legacy/$1 last;  # 规则B
    }
}

执行顺序分析：请求/old/item123会先触发规则A的301重定向，而不会执行规则B。需调整配置顺序或使用location块的条件约束。

2.5 缓存导致的误判

某次故障排查记录：工程师修改规则后反复测试无效，最终发现是浏览器缓存了301永久重定向。解决方案：

# 开发环境使用302临时跳转
rewrite ^/test/(.*)$ /new/$1 redirect;

# 生产环境上线时改为301
rewrite ^/prod/(.*)$ /new/$1 permanent;

三、深度排查实战演练

3.1 日志分析技巧

开启调试日志：

error_log /var/log/nginx/error.log notice;
rewrite_log on;

典型日志解读：

2024/02/20 14:23:12 [notice] 1234#1234: *1 "^/api/v1/(.*)" matches "/api/v1/users", client: 192.168.1.1...
2024/02/20 14:23:12 [notice] 1234#1234: *1 rewritten data: "/v2/users", args: ""

3.2 使用curl模拟测试

高级测试命令：

# 跟踪重定向过程
curl -vL http://example.com/old-path

# 测试特定User-Agent的重写
curl -A "Mozilla/5.0 (iPhone)" http://example.com/mobile-check

3.3 条件判断进阶用法

复杂规则示例：

map $http_user_agent $is_mobile {
    default 0;
    ~*(android|iphone) 1;
}

server {
    if ($is_mobile) {
        rewrite ^/desktop/(.*) /mobile/$1 redirect;
    }
}

▶ 注意事项：map指令需放在http块内，与rewrite配合实现设备识别

四、性能优化与安全实践

4.1 正则表达式优化

低效写法：

rewrite ^/(a|b|c|d|e|f|g|h|i|j|k|l|m|n|o|p|q|r|s|t|u|v|w|x|y|z)+$ /index.html;

优化方案：

rewrite ^/[a-z]+$ /index.html;

性能对比：字符集匹配效率比多重分支选择高3倍以上

4.2 防范安全风险

危险配置示例：

rewrite ^/(.*) /index.php?url=$1;

安全隐患：可能引发路径穿越攻击，改进方案：

rewrite ^/([a-zA-Z0-9-_/]+)$ /index.php?url=$1;

4.3 与try_files的配合使用

混合使用示例：

location / {
    try_files $uri $uri/ @router;
    rewrite ^/static/(v\d+)/css/(.*) /static/css/$2;
}

location @router {
    rewrite ^/(.*)$ /index.php?_route=/$1 last;
}

▶ 最佳实践：优先使用try_files处理静态文件，rewrite处理动态路由

五、综合解决方案模板

5.1 标准排查流程

  1. 检查nginx -t配置语法
  2. 清空浏览器缓存并用curl测试
  3. 查看error_log和rewrite_log
  4. 检查location块的匹配顺序
  5. 验证正则表达式在线工具（如regex101.com）

5.2 高频问题速查表

现象描述 可能原因 解决方案
重写规则部分生效 正则表达式未全局匹配 添加正则的起始结束锚点
无限循环重定向 last标志使用不当 改用break或调整规则顺序
参数丢失 未保留$query_string 在目标URL添加$args
PC端跳转移动版失效 User-Agent检测条件错误 更新设备识别正则表达式

5.3 企业级配置示例

电商平台URL重写方案：

map $http_user_agent $device_suffix {
    ~*(android|iphone) '-m';
    default '';
}

server {
    # 商品详情页统一规范
    rewrite ^/p-(\d+).html$ /product/$1 permanent;
    
    # 多端适配重写
    rewrite ^/product/(\d+)$ /gateway$device_suffix/$1 last;
    
    # 旧版API兼容
    if ($args ~* "^(.*)version=1.0(.*)$") {
        rewrite ^/api/(.*) /v1/api/$1?$args permanent;
    }
}

六、技术方案对比分析

6.1 rewrite与return的抉择

rewrite指令 return指令
适用场景 复杂路径转换 简单跳转
性能影响 较高 极低
正则支持 完全支持 有限支持
请求处理 可继续执行 立即终止

6.2 各flag的应用差异

rewrite ^/old /new redirect;   # 302临时跳转（客户端可见）
rewrite ^/old /new permanent; # 301永久跳转（SEO友好）
rewrite ^/old /new last;       # 停止处理，重新匹配location
rewrite ^/old /new break;      # 立即终止，使用当前结果

七、总结与最佳实践

7.1 经验总结

  • 在测试环境使用redirect而非permanent
  • 复杂正则建议先在regex101.com验证
  • 使用curl -IL快速查看重定向链
  • 重要规则变更前备份配置文件

7.2 推荐工具集合

  1. Nginx调试神器：nginx -T（查看完整配置）
  2. 流量重放工具：goaccess
  3. 正则表达式验证：regex101.com
  4. 性能测试：wrk