瓦片缓存 30 天不清，改了配色用户看到的还是旧图

现象

GeoServer 里改了 SLD 配色，重新生成了瓦片。 本地 Ctrl+F5 后看到的是新配色， 但线上用户反馈仍是旧版，持续了三天。

响应的缓存策略是 Cache-Control: max-age=2592000， 即 30 天，URL 里没有任何版本号。

原因

max-age 期间浏览器不会再发请求验证， 直接从磁盘缓存读取。URL 不变，浏览器就认为资源没变， 服务端即使已经更新，客户端也拿不到。

瓦片类资源本来就适合长缓存，但前提是URL 可版本化： /tiles/v1/{z}/{x}/{y}.png 改成 /tiles/v2/...，版本号一变，自然获得新资源。

排查过程

1. 在开发者工具里选中瓦片，看 Size 列是否显示 (disk cache)。
2. 看响应头 Date 与 Age，判断缓存已存放多久。
3. 在地址后加随机参数 ?v=2 请求一次，若立即出现新图，确认是缓存问题。
4. 检查是否有 CDN 层额外缓存，CDN 的 Age 也需要清。

# 跳过缓存验证服务端内容
curl -H "Cache-Control: no-cache" -I https://tile.example.com/10/843/392.png

# 响应头示例
# Cache-Control: public, max-age=2592000
# Age: 1296000        <- 已缓存 15 天

解决方案

在 URL 里加版本号，并配合长缓存。版本号变更时旧瓦片仍可用，不需要强制刷新。

# Nginx：按版本目录设置长缓存
location ~ ^/tiles/v(\d+)/ {
  root /var/www/tiles;
  expires 1y;
  add_header Cache-Control "public, max-age=31536000, immutable";
}

# 未版本化的旧路径改为短缓存，给迁移留缓冲
location /tiles/ {
  expires 1h;
  add_header Cache-Control "public, max-age=3600, must-revalidate";
}

// 前端：把版本常量集中管理，发版时只改一处
const TILE_VERSION = 'v3';
L.tileLayer(`https://tile.example.com/tiles/${TILE_VERSION}/{z}/{x}/{y}.png`, {
  maxZoom: 18,
  tileSize: 256
}).addTo(map);

// 应急：给已加载的图层强制重载（只对当前会话有效）
layer.setUrl(`https://tile.example.com/tiles/v3/{z}/{x}/{y}.png?t=${Date.now()}`);

验证

新版本 URL 首次请求返回 200 与新图，再次请求命中缓存返回 200 (from disk cache)；旧版本 URL 仍能访问，不影响回滚。

const urls = performance.getEntriesByType('resource')
  .map(e => e.name).filter(n => n.includes('/tiles/'));
console.assert(urls.every(u => u.includes('/tiles/v3/')), '仍有旧版本瓦片请求');

适用版本