先给结论,再说现状与补法:
- 可安装:
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 等)根本不归它管。
真要离线怎么补
- 把 SW 文件放到宿主
wwwroot根(如/sw.js),register时作用域才是/;想继续用框架那份,至少显式传{ scope: '/' }并把它挪到可被根路径访问的位置。 install里填真正的 app shell 清单(index.html、_framework/blazor.boot.json与 wasm 资源、_content/Known/css/web.css),activate里清理旧版本缓存。fetch里做「导航请求网络优先 + 失败回落index.html」,「静态资源 cache-first」;API 请求不要缓存(Known 的[WebApi]全走POST,缓存无意义且会串数据)。- 版本号跟着构建走(文件名 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:未实现,本地文件读写交给宿主。
相关
- 部署形态与缓存头(
index.html不能被长效缓存)见 Linux 部署指南。 theme_color与品牌色的一致性见 深浅色主题。- 桌面(离线)运行见 移动端应用外壳 与
KnownWin宿主说明。
扫码关注公众号
扫码加入 QQ 群