PWA / 离线

宿主侧 manifest 让应用"可安装";Service Worker 目前只是占位(不预缓存、fetch 直通),真要离线请用 KnownWin。

最后更新

先给结论,再说现状与补法:

  • 可安装:KnownWeb/wwwroot/manifest.json 已在仓里,浏览器地址栏的「安装」可用——桌面图标、独立窗口、主题色都对。
  • 不可离线:Known/js/serviceWorker.js 只是骨架,install 里 cache.addAll([])(空清单)、fetch 监听体为空,一个字节都不缓存;注册作用域还被限制在 /_content/Known/js/,覆盖不到页面路由。断网后刷新必然失败。
  • 真离线:用 KnownWin(WebView2 + 本地 SQLite),数据在本机、启动不依赖网络。框架不在 Web 端堆离线缓存。

仓里实际有什么

manifest

KnownWeb/wwwroot/manifest.json:

{
  "name": "Known",
  "short_name": "Known",
  "start_url": "./",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#03173d",
  "icons": [
    { "src": "icon-512.png", "type": "image/png", "sizes": "512x512" },
    { "src": "icon-192.png", "type": "image/png", "sizes": "192x192" }
  ]
}

同目录带 favicon.png / icon-192.png / icon-512.png。theme_color 决定系统窗口边框与桌面 tile 底色,background_color 只管启动瞬间的底色。

KnownWasm/wwwroot/index.html 里也有一行 <link rel="manifest" href="manifest.json" />,但纯静态 WASM 宿主的 wwwroot 下没有这份文件——自行部署 WASM 时要补一份(或在 index.html 里改指 _content/Known/...),否则控制台一条 404。

Service Worker

注册在 Known/wwwroot/js/web.js('serviceWorker' in navigator 附近):

// Blazor Hybrid 桌面宿主(WebView2 基址固定 https://0.0.0.0)没有可注册 SW 的真实源,跳过。
if ('serviceWorker' in navigator && location.hostname !== '0.0.0.0') {
    window.addEventListener('load', () => {
        navigator.serviceWorker.register('/_content/Known/js/serviceWorker.js');
    });
}

脚本本身(Known/wwwroot/js/serviceWorker.js)是占位:

const KNOWN_WEB_CACHE = "known-web-cache";

self.addEventListener("install", e => {
    e.waitUntil(caches.open(KNOWN_WEB_CACHE).then(cache => cache.addAll([])));   // 空清单
});

self.addEventListener("fetch", () => { });                                        // 直通

两处限制要清楚:缓存清单是空的,所以没有任何资源进 CacheStorage;注册路径在 /_content/Known/js/ 下,作用域默认就是那一层,页面路由(/、/report 等)根本不归它管。

真要离线怎么补

  1. 把 SW 文件放到宿主 wwwroot 根(如 /sw.js),register 时作用域才是 /;想继续用框架那份,至少显式传 { scope: '/' } 并把它挪到可被根路径访问的位置。
  2. install 里填真正的 app shell 清单(index.html、_framework/blazor.boot.json 与 wasm 资源、_content/Known/css/web.css),activate 里清理旧版本缓存。
  3. fetch 里做「导航请求网络优先 + 失败回落 index.html」,「静态资源 cache-first」;API 请求不要缓存(Known 的 [WebApi] 全走 POST,缓存无意义且会串数据)。
  4. 版本号跟着构建走(文件名 hash 或 CACHE_VERSION 常量),否则用户会一直吃旧壳。

补完之前,别在项目文档里写"离线可用"——这是本页要纠正的口径。

营销站

Website/wwwroot/manifest.webmanifest 已存在,Website/App.razor 挂 <link rel="manifest" href="/manifest.webmanifest" />:只为「添加到桌面」有个像样的名字与图标(standalone、theme_color: #2F5BFF)。

营销站不注册 Service Worker:没有账号态、没有 API,内容更新频繁,加了 SW 反而要维护强更逻辑,容易让用户看不到新版。

有意不做

  • Push 通知:未实现。
  • Background Sync(离线写操作回放):未实现。
  • File System Access API:未实现,本地文件读写交给宿主。

相关

微信公众号二维码 扫码关注公众号
QQ 交流群二维码 扫码加入 QQ 群