nginx可通过预生成webp文件实现零开销自动返回，需同时满足：注册image/webp mime类型、在http块顶层配置map指令映射$webp_suffix、location中按序使用try_files $uri$webp_suffix $uri =404、添加add_header vary accept确保缓存正确。
.webp 文件——前提是 MIME 类型注册、map+try_files 配置正确、Vary Accept 头和缓存策略同步生效，缺一不可。
确认 WebP MIME 类型已注册
如果 Nginx 不认识 .webp 后缀，即使文件存在，也会返回 404 或触发下载而非渲染。
- 打开
/etc/nginx/mime.types（或主配置中types { }块） - 确保包含这一行：
image/webp webp; - 若使用
include mime.types;，该行必须在mime.types文件内；否则直接加到http { }块里 - 改完后执行
nginx -t验证，再nginx -s reload
用 map + try_files 实现自动回退
这是最稳定、无性能损耗的方式，依赖预生成的 .webp 文件（如 /images/photo.jpg.webp），不是实时转换。
-
map必须写在http { }块顶层，不能放server或location内，否则报错"map directive is not allowed here" - 推荐写法：
map $http_accept $webp_suffix { "~*webp" ".webp"; default ""; } - 图片
location中用：try_files $uri$webp_suffix $uri =404;——顺序不能颠倒，否则跳过 WebP - 路径必须一致：若原图是
/a/b/c.png，WebP 必须是/a/b/c.png.webp；try_files不会帮你改扩展名
Vary Accept 和缓存策略必须同步生效
不加 Vary: Accept，CDN 或代理会把 WebP 版本缓存下来，再给不支持 WebP 的用户返回，导致白屏或乱码。
- 在匹配图片的
location块中加：add_header Vary Accept; - 避免在
root或alias混用：若用了alias /data/img/;，$uri不含前缀，$uri.webp就会拼成错误路径（如/photo.jpg.webp而非/data/img/photo.jpg.webp） - 可配合
expires差异化缓存：map $sent_http_content_type $cache_time { "~*image/webp" "1y"; default "7d"; }，再在location中写expires $cache_time;
常见故障排查点
配置看似正确却始终返回原图？优先检查这四件事：
- 用
curl -H "Accept: image/webp" -I http://yoursite.com/test.jpg看响应头是否含Content-Type: image/webp - 手动
ls /path/to/test.jpg.webp，确认文件真实存在且权限可读 - 检查
nginx -t输出是否有 warning，比如重复声明 MIME 类型"image/webp" - 浏览器开发者工具 Network 标签页中，查看该请求的 Response Headers 是否含
Vary: Accept；不含说明配置未生效
map 放错位置、alias 导致路径拼接失败、CDN 忽略 Vary，任何一个环节断掉，WebP 就形同虚设。
