静态Brotli文件未命中会导致页面白屏、乱码或回退未压缩响应，核心排查点是.br文件是否存在且路径完全匹配、权限正确、brotli_static置于有效location块内、Content-Type一致，并排除CDN等中间层干扰Accept-Encoding协商。
静态 Brotli 文件未命中，页面可能白屏、乱码或回退到未压缩响应，但 Nginx 日志往往不报错——问题不在崩溃，而在“静默跳过”。排查核心是确认 .br 文件是否被真正找到、读取并返回，而非仅看配置语法是否正确。
检查 .br 文件是否存在且路径完全匹配
Nginx 的 brotli_static on 是严格路径匹配，不是模糊查找：
- 请求 URL 是
/js/app.abc123.js，Nginx 就只去找磁盘上同名的/path/to/js/app.abc123.js.br（注意后缀是.js.br，不是.br单独后缀） - 用
ls -l /full/path/to/js/app.abc123.js.br确认文件真实存在，且大小明显小于原始.js文件（否则可能是空文件或生成失败） - 检查 Nginx worker 进程用户（如
www-data或nginx）对该.br文件有读权限：ls -l输出中需含r--权限位
验证 brotli_static 是否在正确作用域启用
该指令必须写在能覆盖目标资源的 location 块内，全局 http 块中的设置无效：
- 错误写法：
http { brotli_static on; }→ 不生效 - 正确写法：
location ~ \.js$ { brotli_static on; }或location /static/ { brotli_static on; } - 若使用正则 location，确保请求路径确实匹配（例如
/static/v1/main.js匹配location ~ \.js$，但不匹配location ^~ /static/后的子路径逻辑）
比对响应头与原始文件的 Content-Type
未命中时浏览器常显示乱码，根本原因常是 Content-Type 错误，而非压缩本身：
- 用
curl -I https://yoursite.com/js/app.js查响应头：若无Content-Encoding: br，说明未命中；若有但内容乱码，重点查Content-Type -
Content-Type必须与原始.js文件一致（如application/javascript），不能是text/plain或application/octet-stream - 检查 Nginx 的
types配置是否包含application/javascript js;；避免在 location 中误设default_type text/plain; - 对比直接请求
.js和.js.br的响应头：curl -I https://yoursite.com/js/app.js与curl -I https://yoursite.com/js/app.js.br的Content-Type应完全相同
确认 Accept-Encoding 协商未被干扰
即使 .br 文件就绪，中间层也可能剥离 br 导致协商失败：
- 用
curl -H "Accept-Encoding: br" -I https://yoursite.com/js/app.js模拟支持 Brotli 的客户端，观察是否返回Content-Encoding: br - 若本地 curl 能命中，但浏览器不行，检查 CDN、WAF 或反向代理是否过滤了
Accept-Encoding: br（常见于老旧网关或安全策略） - 在 Nginx 配置中临时加一行
add_header X-Brotli-Status "$brotli_ratio";，命中时该 header 显示数值（如3.5），未命中时为空或0.0
