Atlaslog / Field Notes / Tiles
Field note · Tiles
Tiles cached for 30 days keep showing the old styling
Quick answer
The service re-seeded tiles with a new SLD, but users still see the old basemap days later. `Cache-Control: max-age=2592000` on an unversioned URL means browsers never revalidate and keep reading the disk copy.
Symptom
- The response header is `Cache-Control: public, max-age=2592000` with `Age: 1296000`, and dev tools shows `(disk cache)`
- `Ctrl+F5` shows the new colors locally while production users still see the old ones
- Appending `?v=2` to the tile URL immediately returns the new tile
Checklist
- Check whether the Size column says `(disk cache)` for the tile
- Read `Date` and `Age` to see how long the object has been stored
- Request the tile with a random query parameter and see whether the new image appears
- Check for an additional CDN cache layer and its `Age`
- Confirm the URL contains no version segment
Fix
Put a version in the path (`/tiles/v3/{z}/{x}/{y}.png`) and serve it with `max-age=31536000, immutable`, while unversioned paths drop to `max-age=3600, must-revalidate`; bump the version constant in one place on release.
Code
# 跳过缓存验证服务端内容
curl -H "Cache-Control: no-cache" -I https://tile.example.com/10/843/392.png
# 响应头示例
# Cache-Control: public, max-age=2592000
# Age: 1296000 <- 已缓存 15 天# 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";
}
Watch out
- Serving new headers on the same URL, since already-cached clients keep the old copy until max-age expires
- Purging only the CDN, which does nothing for browser caches
English edition written for Atlaslog from the original Chinese field note. Code is unchanged and runs as-is.
Atlaslog (2026). Tiles cached for 30 days keep showing the old styling. https://www.jingweizhi.com/en/cookbook/tile-cache-maxage.html (accessed 2026-11-03).