地图已经替换,某些手机却仍显示旧楼层;店铺名称更新了,路线终点还停在原来的位置。遇到这种情况,直接让用户清缓存,往往只能暂时掩盖问题。
H5室内导航涉及页面、地图资源、兴趣点数据和路线服务。界面上的一次“打开地图”,背后可能包含多次请求。只要这些请求拿到不同批次的数据,就可能出现画面更新了、导航关系却没有同步更新的情况。
本文以一个自定义导航前端为例,讨论怎样区分缓存问题与版本混用问题。文中的地址、字段和发布流程均为设计示例,不代表某个SDK已提供同名接口。
一、先判断旧内容来自哪里
不能只看浏览器有没有刷新
排查时,应记录发生异常的具体资源URL、响应内容及当前页面识别的版本,而不是只记录“手机显示不对”。同一个URL背后,至少可能存在几类缓存。
| 层次 | 要观察什么 | 容易出现的误判 |
|---|---|---|
| 浏览器HTTP缓存 | 请求是否来自内存或磁盘,实际响应头是什么 | 把本地旧响应误认为CDN没有更新 |
| CDN节点 | 缓存命中情况、响应头、请求路径与缓存键配置 | 以为改了源站文件,各节点就会同步清空 |
| 源站或应用服务 | 直连源站时拿到的内容及应用版本 | CDN已经回源,但源站仍返回旧内容 |
| 前端自建缓存 | 若使用Service Worker、Cache Storage或IndexedDB,检查其更新策略 | 把应用自己保存的数据当作普通HTTP缓存 |
阿里云CDN排障文档也将浏览器本地缓存、存量节点缓存和源站自身缓存列为内容未更新时需要分别检查的对象。修改过期时间,不等于自动删除之前缓存的对象。
no-cache不是“不允许存储”
按HTTP缓存语义,no-cache要求复用前进行验证;no-store用于禁止缓存存储。二者不能当作同一个开关。CDN产品还可能有自己的缓存配置及覆盖选项,不能只看源站的一行响应头就推断整条链路的结果。
实际排查可以先选一个异常资源,比较浏览器访问与源站内容,再检查CDN规则和前端持久缓存。无痕窗口可辅助定位,但不能替代普通用户环境下的最终检查。
二、比“全部清缓存”更重要的是固定一份完整版本
用发布清单约束地图、兴趣点与路网
假设一个楼层的地图、店铺数据和路网分别更新。即使每个请求单独都成功,也不能说明三份数据可以组合使用。
一种做法是将互相依赖的数据组织成一个发布版本,再通过清单告诉前端本次该加载哪些资源:
{
"release_id": "venue-a-r42",
"map": "/releases/r42/map.a81f.json",
"poi": "/releases/r42/poi.b39c.json",
"graph_version": "graph-r42"
}
这里的r42是示例发布号,文件名后缀用于表达内容版本,并非真实文件哈希。前端读取清单后,应在一次加载过程中固定使用该清单,不能加载地图时取一次“最新版本”,查询路线时又自行切到另一份“最新版本”。

图1:导航数据的版本发布与加载关系示意。
路线服务也要认识这个版本
如果路线由服务端计算,前端只有一个静态清单仍不够。请求应携带本次加载对应的路网版本,响应也应返回实际采用的版本。接口找不到该版本时,应明确返回版本不可用,而不是静默换用另一份路网。
例如,前端固定在r42,路线响应却标为graph-r41,此时应阻止把结果直接画在r42地图上,转入重载或提示流程。这样更容易暴露一致性问题,避免用户看到一条看似正常、实际与地图不对应的路线。
“绑定版本”不意味着正在导航的会话永远不能更新。可以在开始新路线、切换地图或发现旧版本失效时检查更新;关键是更新相关资源后再统一切换,不能在半途悄悄替换其中一份数据。
三、缓存时间按资源职责设计
稳定资源与更新入口分开处理
| 对象 | 一种可选策略 | 使用前提 |
|---|---|---|
| 带内容版本的地图、图标与兴趣点文件 | 允许较长缓存 | 发布后不覆盖同一路径;更新时使用新地址 |
| 指向当前发布版本的清单 | 采用短有效期或验证机制 | 检查浏览器与CDN的实际规则,而非只改前端代码 |
| 带会话或个人信息的路线响应 | 按接口安全与实时性要求设计缓存,必要时禁止存储 | 不能套用静态文件的长缓存规则 |
| 临时封闭、动态通行状态 | 单独管理有效期与更新来源 | 不能因底图版本稳定就长期忽略动态变化 |
这些是设计选择,不是阿里云统一推荐的固定TTL。使用阿里云CDN时,还应检查目录规则、文件后缀规则、源站响应头及是否启用覆盖行为,确保真正命中的策略与预期一致。
如果采用查询参数区分版本,需要确认CDN缓存键是否保留相关参数。更换了参数却仍命中同一份缓存,是需要单独排查的配置问题。
先准备新版本,再更新入口
发布顺序可以设计为:先上传新资源并检查可读取性,再准备匹配的路线数据,最后更新清单指向。旧资源保留一段与会话策略匹配的时间,供尚未结束的旧会话继续使用。
更新清单并不意味着所有客户端同时切换。某个客户端仍取得r41清单,另一个取得r42清单,是缓存传播过程中可能存在的状态。设计目标首先是让每个客户端内部的数据保持自洽,并明确何时需要升级。
回退时,也应回退到一份完整清单。只回退地图文件、保留新路网,会重新制造版本混用。对于已失效或涉及通行安全的旧版本,应按业务要求停用,不能为了不中断界面而无限保留。
四、让日志能回答“用户当时用了哪一版”
可以在前端诊断信息中保留地图ID、发布号、资源地址、路网版本和路线请求ID。服务端日志记录实际使用的版本,发生异常时才能把截图与请求对应起来。
维小帮公开产品资料包含导航H5、地图编辑器及地图SDK等形态。对于这类前端地图与业务数据协同的应用,值得讨论的不只是页面是否加载成功,还包括资源与业务数据在更新时如何配合。本文提出的清单机制属于通用架构分析,不能直接当作现有产品接口说明。
当下一次遇到“地图更新了,手机却还是旧的”,可以先回答两个具体问题:旧响应来自哪一层?同一会话的地图、兴趣点和路线采用的是不是同一份发布数据?前者帮助定位缓存,后者帮助判断系统是否具备可控的更新边界。