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-*）更可靠。
-
推荐做法：
- 现代阈值只设置必要下限；
- 未列出 UA 默认现代或古老需结合业务评估；
- 保留回退资源，避免硬错误；
- 定期回顾版本范围，或用 CI 脚本自动生成配置。
掌握
ngx_http_browser_module，让你在 NGINX 这一层就能优雅地把“古董浏览器”隔离在现代 Web 体验之外。祝开发愉快！