PWA
将站点安装到桌面或主屏幕并使用静态资源缓存
PWA 功能会在生产环境为站点注册 Service Worker，并通过 Web App Manifest 让浏览器把站点安装到桌面或主屏幕，本节介绍安装、离线缓存、资源更新和部署要求。
安装站点
使用生产环境地址打开站点，在支持 PWA 的浏览器菜单或地址栏中选择「安装」即可将站点添加到桌面；移动端浏览器通常使用「添加到主屏幕」完成安装。iPhone 和 iPad 可以在 Safari 的分享菜单中选择「添加到主屏幕」，不同浏览器显示的名称可能略有区别。
安装入口依赖浏览器对当前站点的识别结果，站点需要使用 HTTPS，且浏览器能够访问清单文件和 Service Worker。安装后从桌面或主屏幕打开站点时，会使用独立窗口显示，不再显示普通浏览器标签页的地址栏；点击应用图标会从清单中配置的起始地址进入站点首页。
应用清单
PWA 清单文件位于 public/manifest.webmanifest，生产页面通过 /manifest.webmanifest 引用。清单中的 name 和 short_name 用于应用名称，description 用于应用描述，theme_color 和 background_color 用于启动和窗口颜色，display 当前设置为 fullscreen，start_url、scope 和 id 都以站点根路径为范围。
JSON{
"name": "ImQi1",
"short_name": "ImQi1",
"description": "做技术的分享者、生活的摄影师、时事的评论员。",
"theme_color": "#f9fafb",
"background_color": "#ffffff",
"display": "fullscreen",
"lang": "zh-CN",
"start_url": "https://imqi1.com",
"scope": "https://imqi1.com",
"id": "/",
"icons": [
{
"src": "/imgs/imqi1.svg",
"sizes": "192x192",
"type": "image/svg+xml",
"purpose": "any maskable"
},
{
"src": "/imgs/imqi1.svg",
"sizes": "512x512",
"type": "image/svg+xml",
"purpose": "any maskable"
}
]
}清单文件还配置了 192×192 和 512×512 两个应用图标，以及桌面端和移动端截图。部署其他站点时，需要同步修改清单中的名称、地址、图标和截图路径；清单是静态文件，不会随着 site.config.ts 中的站点名称自动生成，修改后需要重新构建并发布。
请将清单内的信息改为贵站的信息，不要使用我的。
离线缓存
首次在线访问并完成 Service Worker 激活后，站点会预缓存 favicon.ico 和字体样式表；访问过程中产生的 CSS、JavaScript、图片、视频、音频和字体资源也会按类型写入浏览器缓存。静态资源使用 Cache First 策略，缓存数量和有效期由构建配置统一控制，单类资源最长保留一年，超过数量后会淘汰较旧的缓存。
PWA 当前缓存的是静态资源，不会把文章、评论、订阅、地图数据或后台接口结果保存为离线数据。页面仍然由服务端渲染，离线时不能依赖新的页面内容和接口请求；路由也没有配置 SPA 离线回退，因此不能把 PWA 当作完整的离线应用使用。
更新资源
项目使用 registerType: "prompt" 注册 Service Worker。发布新版本后，新的 Service Worker 会先等待当前页面结束，不会直接中断正在浏览的页面；重新加载页面后，浏览器会让新的 Service Worker 接管并使用本轮构建的资源。若页面长时间保持打开，关闭站点页面后再重新访问即可完成切换。
生产构建会生成构建哈希，构建产物的 JavaScript 和 CSS 使用本轮哈希目录，postbuild 会执行 update-sw-cdn.ts，更新 sw.js 中的预缓存资源地址，并将 Service Worker 复制到服务端根目录。修改 PWA 配置或清单文件后，重新执行以下命令生成新的生产产物：
Bashbun run build开发环境
开发服务器默认关闭 PWA，执行 bun run dev 时不会注册 Service Worker，也不会出现安装入口。需要验证安装、清单和缓存行为时，先执行 bun run build，再使用 bun run preview 启动生产构建的预览服务，并在浏览器中通过 HTTPS 或受信任的本地环境访问。
生产部署
部署时需要让主站根域名能够直接提供 /sw.js，并返回 Service-Worker-Allowed: / 和禁止长时间缓存的响应头。Service Worker 必须从主站提供，不能只放在跨域 CDN 上；manifest.webmanifest、应用图标和其他静态资源也要保持清单中的路径可以访问。
使用 Nginx 反向代理时，可以执行 bun run nginx:generate 生成包含 Service Worker、Manifest 和静态资源规则的参考配置。配置 CDN 后，构建脚本会把带哈希的 JavaScript 和 CSS 指向 CDN，sw.js 仍作为根路径入口保留在主站；具体的静态资源上传方式见 CDN 配置，完整构建过程见 构建流程。