打开本地开发环境的 http://localhost:3000,明明启动的是一个新项目,浏览器却始终显示之前使用过的 Cicada 白板工具。必须强制刷新才能看到真正的页面,普通刷新又是白板工具。
这说明就是浏览器中的某种缓存机制导致,肯定不是服务器端问题。
经过 AI 的介绍,了解到这其实是浏览器中的 Service Worker 缓存机制导致的。
Service Worker 是运行在浏览器后台的脚本,可以拦截其作用域内的网络请求,并根据预设策略决定从网络获取资源,还是直接返回本地缓存。它主要用于 PWA 离线访问、资源缓存和推送通知等功能。
需要注意,Service Worker 的注册信息会持久保存在浏览器中,不会因为开发服务器重启而自动消失。只要协议、域名和端口组成的 Origin 不变,原来的 Service Worker 就可能继续控制页面。
例如,之前某个项目在 http://localhost:3000 注册了 Service Worker,并缓存了 index.html。当你后来启动另一个项目,仍然使用这个地址时,浏览器可能会启动原来的 Service Worker,拦截页面导航请求,直接返回旧项目缓存的 HTML,而不是访问当前开发服务器。
这就解释了为什么每次打开 3000 端口,看到的都是同一个旧工具。
解决方法是清理 Service Worker 注册和相关缓存。
在 Edge 或 Chrome 中打开 http://localhost:3000,按 F12 进入开发者工具,切换到 Application(应用程序)面板,找到 Service Workers,点击 Unregister 注销注册;
然后进入 Storage(存储),执行 Clear site data,清理 Cache Storage 等站点数据,最后重新打开页面。
也可以在控制台执行:
await navigator.serviceWorker.getRegistrations().then((rs) => Promise.all(rs.map((r) => r.unregister())));
await caches.keys().then((keys) => Promise.all(keys.map((k) => caches.delete(k))));
需要注意,这段代码只能清理当前页面 Origin 下的注册和缓存,不能清理其他端口或域名的数据。
对于本地开发环境,建议默认不要启用 PWA Service Worker,尤其是 Vite 项目,应检查 vite-plugin-pwa 是否意外开启了开发环境注册功能。
核心问题在于:浏览器中的 Service Worker 注册具有持久性,开发服务器重启并不会清理它。 当本地页面出现与实际服务不一致的情况时,除了检查端口和服务进程,也应该排查 Service Worker 和浏览器缓存。