NGINX `ngx_http_browser_module` 深度解析与实战

1. 模块定位

ngx_http_browser_module 在 HTTP 头 User-Agent 解析的基础上，给出三个内置变量：

变量	作用	典型值
$modern_browser	当 UA 被判定为 现代浏览器 时取 modern_browser_value 指定的值；否则为空	modern. / 1
$ancient_browser	当 UA 被判定为 古老浏览器 时取 ancient_browser_value 指定的值；否则为空	1
$msie	只要 UA 匹配任何版本 IE 就是 1	1

借助这 3 个变量，可在 index 选择、资源路径拼接、重定向、灰度开关 等场景灵活使用。

2. 四大指令

指令	作用	常用写法
modern_browser	声明 哪些浏览器从哪个版本起算作现代；unlisted 可把未列出 UA 归入现代或古老	modern_browser msie 5.5;
modern_browser_value	给 $modern_browser 变量赋值	modern_browser_value "modern.";
ancient_browser	指定 UA 子串，将对应浏览器标记为古老	ancient_browser Links Lynx netscape4;
ancient_browser_value	给 $ancient_browser 变量赋值	ancient_browser_value 1;

版本号格式：X / X.X / X.X.X / X.X.X.X，最大分别支持 4000 / 4000.99 / …
特别关键字：netscape4 ⇢ 正则 ^Mozilla/[1-4]

3. 经典落地方案

3.1 动态选择首页

# 现代浏览器追加前缀 "modern."
modern_browser_value "modern.";modern_browser msie      5.5;
modern_browser gecko     1.0.0;
modern_browser opera     9.0;
modern_browser safari    413;
modern_browser konqueror 3.0;# 拼接变量，自动加载 index.modern.html 或 index.html
index index.${modern_browser}html index.html;

• IE≥5.5 / Firefox≥1.0 / Chrome / Safari≥413 等加载 index.modern.html
• 其余浏览器加载回退版 index.html

3.2 拦截古老浏览器

# 定义现代浏览器最低版本
modern_browser msie 5.0;
modern_browser gecko 0.9.1;
modern_browser opera 8.0;
modern_browser safari 413;
modern_browser konqueror 3.0;
modern_browser unlisted;     # 未列出 UA 视作现代（也可去掉改为古老）# 指定古老 UA 关键字
ancient_browser Links Lynx netscape4;# 赋值
ancient_browser_value 1;# 若被判定为古老，重定向提示页
if ($ancient_browser) {return 302 /ancient.html;
}

3.3 仅针对 IE 执行兼容脚本

# 在响应头里注入一个自定义变量，供前端判断
add_header X-IE-Compat $msie;

4. 常见坑与优化

问题	解决方案
UA 伪造 导致误判	UA 基于客户端，无法 100 % 准确；仅适用于体验优化而非安全验证
新浏览器版本频繁出现	建议 modern_browser unlisted; 并通过 CI/CD 定期补充版本阈值
判断逻辑复杂	可以将多行指令抽成 include conf/modern_browsers.conf; 维护
需根据 $modern_browser 拼接路径	记得提供 兜底文件，防止 404

5. 结合其他 NGINX 模块

模块	组合示例	效果
ngx_http_rewrite_module	if ($modern_browser) { rewrite ^ /modern$uri break; }	目录级别灰度
ngx_http_map_module	map $modern_browser $asset_prefix { "" ""; "modern." "v2/"; }	动态前缀映射
ngx_http_sub_module	根据 $msie 注入 polyfill 脚本	高级响应改写

6. 总结

• 配置轻量：只需四条指令即可完成浏览器年龄分层。

• 业务价值：前端灰度、兼容兜底、运营 A/B 实验的 NG 层实现。

• 局限：依赖 UA，安全不可用；现代内容协商（Accept-*）更可靠。

• 推荐做法：

  1. 现代阈值只设置必要下限；
  2. 未列出 UA 默认现代或古老需结合业务评估；
  3. 保留回退资源，避免硬错误；
  4. 定期回顾版本范围，或用 CI 脚本自动生成配置。

掌握 ngx_http_browser_module，让你在 NGINX 这一层就能优雅地把“古董浏览器”隔离在现代 Web 体验之外。祝开发愉快！