Nginx可通过预生成WebP文件实现零开销自动返回，需同时满足：注册image/webp MIME类型、在http块顶层配置map指令映射$webp_suffix、location中按序使用try_files $uri$webp_suffix $uri =404、添加add_header Vary Accept确保缓存正确。

Nginx 本身不生成 WebP，但能零开销自动返回预生成的 .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），不是实时转换。

Computer Use Linux

顶级 Linux 计算机使用技能，配套独立自举运行时，无需本地 Claude 安装、私有原生模块等。

下载

• 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 就形同虚设。