Nginx proxy_cache缓存地图瓦片需精准识别z/x/y路径唯一性、剔除动态参数干扰、长期缓存（如200/302缓存30天），并配置proxy_cache_key剔除$arg_z等以外的干扰项，配合proxy_ignore_headers和cache_lock保障命中率与并发安全。
在 Nginx 中用 proxy_cache 缓存地图瓦片（如 XYZ 或 TMS 格式），核心是让 Nginx 识别瓦片请求的唯一性（z/x/y + 格式），跳过动态参数干扰，并长期缓存静态资源。关键不在“配 cache”，而在“让 cache 正确命中且不被绕过”。
一、定义缓存区与基础策略
在 http 块中声明共享内存缓存区，控制大小和淘汰机制：
proxy_cache_path /var/cache/nginx/tiles levels=1:2 keys_zone=tiles:100m inactive=7d max_size=20g;
- keys_zone=tiles:100m：分配 100MB 内存存缓存 key 和元数据，足够支撑千万级瓦片
-
inactive=7d：7 天未被访问的缓存自动清理（瓦片冷热分明，比
expires更实用） - max_size=20g：磁盘上限，避免占满根分区
二、精准匹配瓦片路径并启用缓存
地图瓦片 URL 通常形如 /tiles/2.1.0/{layer}/{z}/{x}/{y}.png 或 /arcgis/rest/services/{map}/MapServer/tile/{z}/{y}/{x}。需用 location 精确捕获，避免正则过度匹配：
location ~ ^/tiles/.+\.(png|jpg|webp|pbf)$ {
proxy_cache tiles;
proxy_cache_valid 200 302 30d; # 成功响应缓存 30 天
proxy_cache_valid 404 1m; # 404 也缓存 1 分钟，防刷空请求
proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
proxy_cache_lock on; # 防止缓存穿透时多个请求同时回源
proxy_cache_lock_timeout 5s;
<pre class="brush:php;toolbar:false;">proxy_pass https://tile-backend;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;}
- 用
~而非^~是为了支持扩展名匹配；若路径固定（如全为/tiles/开头），可用^~ /tiles/提升匹配效率 -
proxy_cache_valid 200 302 30d是关键——瓦片极少变更，30 天合理；不要依赖后端的Cache-Control，Nginx 默认会忽略它（除非加proxy_ignore_headers Cache-Control;） -
proxy_cache_lock在高并发加载新瓦片时可减少回源压力
三、处理影响缓存命中的典型问题
以下情况会导致同一瓦片被当成不同请求，无法复用缓存：
aperture: the L402 aware reverse proxy
下载
安装并运行 Aperture（Lightning Labs 的 L402 闪电反向代理），用于创建 L402 付费墙、配置付费 API 端点、为其他代理托管付费内容或测试 L402 认证流程。
-
URL 中带随机参数（如
?t=123456789、&token=xxx）：用proxy_cache_key剔除干扰项 -
HTTP 头差异（如
Accept-Encoding不同导致 gzip/br 版本分离）：统一规范编码或禁用协商 - Cookie 或认证头透传：地图服务通常无状态，应清除无关头
推荐配置：
proxy_cache_key "$scheme$request_method$host$uri$is_args$arg_z$arg_x$arg_y$arg_format"; # 或更稳妥地，对标准 XYZ 路径直接提取： # proxy_cache_key "$scheme$request_method$host$1$2$3$4"; # 配合 location ~ ^/tiles/(\d+)/(\d+)/(\d+)/(\d+\.(png|webp))$
proxy_set_header Accept-Encoding ""; proxy_ignore_headers "Set-Cookie" "Cache-Control" "Expires"; proxy_hide_header Set-Cookie;
四、验证与运维要点
上线后务必验证缓存是否生效：
- 用
curl -I http://your-domain/tiles/12/2048/1536.png查看响应头：X-Proxy-Cache: HIT表示命中，MISS表示首次回源，BYPASS表示被规则跳过 - 检查
/var/cache/nginx/tiles/目录下是否有文件生成（注意：Nginx 不直接写文件名，但du -sh可见增长） - 日志中加入
$upstream_cache_status字段，便于统计命中率
补充建议：
- 首次预热可配合脚本批量请求热门区域（如 z=0~12 的全球底图），避免用户首屏卡顿
- 若后端支持 ETag，可开启
proxy_cache_etag on;（Nginx 1.7.3+），提升条件请求效率 - 瓦片服务升级图层时，可通过修改 URL 路径（如
/tiles/v2/...）自然失效旧缓存，比清缓存更安全
