Skip to content

Latest commit

 

History

History
23 lines (12 loc) · 3.38 KB

pwa.md

File metadata and controls

23 lines (12 loc) · 3.38 KB

PWA 安装与联网游玩

Retrom 可安装到支持的桌面或手机主屏幕,以独立窗口打开。入口固定为首页,登录、游戏库、运行和存档继续使用同一服务器。此版本提供安装引导、界面静态缓存、断网提示和手动更新;不支持断网重新启动游戏或离线浏览私人数据。

PWA 主要面向手机游玩。独立窗口只呈现用户侧功能,即使登录管理员账号,“我的”、侧栏和导航抽屉也不显示管理入口,游戏详情不提供“退回审核”。直接打开 /admin 下的地址会返回首页,不挂载后台页面。进入游戏全屏后仍保持这一行为。普通浏览器标签页保留按账号权限显示的后台,安装应用不会改变当前标签页;管理操作请在浏览器中完成。此处只约束应用界面,服务端角色与授权保持原规则。

安装与使用

正式部署使用 HTTPS。登录后在“账户设置 → Retrom 应用”安装;浏览器支持安装事件时显示按钮,其他浏览器可从菜单安装。iOS 使用分享菜单中的“添加到主屏幕”,并在提供该选项时启用“作为 Web App 打开”。安装完成后从 Retrom 图标启动。安装不改变模拟器、存档身份或手机横屏游玩规则。

本机 localhost 开发属于安全上下文,命名 PFB 地址可用于桌面验证。手机访问开发机的局域网 HTTP 地址不具备同样条件;手机实际安装需受信任的 HTTPS 域名,并将主站和游戏隔离域名一并路由到同一环境。浏览器模拟设备的结果不替代 iOS/Android 真机验收。

缓存与更新边界

根作用域 Service Worker 由 /sw.js 提供,响应禁止 HTTP 缓存。构建按应用源码、图标、配置和依赖锁生成版本,业务源码发布会触发新 Worker 的发现。开发模式不缓存 Next 开发脚本,保留 HMR。

只预缓存自包含的 /offline 文档和安装图标;生产环境按需缓存 /_next/static/ 中声明 immutable 的资源,每个版本最多192项,并保留前一版本供已打开页面的延迟代码加载使用。页面导航始终访问网络,失败或服务端5xx时显示离线提示;不缓存账号页面HTML、RSC响应、业务API、媒体、游戏内容或Provider资源。跨域、iframe、Range和写请求交给原处理链。离线页面保留COOP/COEP/CORP响应头,避免主站缓存削弱隔离。runtime 的OPFS/分块缓存和未同步存档IndexedDB由原模块管理,PWA更新不清理它们。

新 Worker 默认等待,首次安装不刷新页面。回到前台或恢复联网时检查更新,账户页可主动检查。用户点击更新后,Worker 检查同源全部窗口;仍有Player或沉浸界面时拒绝激活并提示先结束游玩。成功激活后仅发起操作的窗口刷新。所有旧版本窗口关闭后,浏览器也可以按标准生命周期激活等待中的版本。退出登录不删除本地存档草稿。

验证

Web 单元回归覆盖缓存边界、离线响应头、存储失败降级、版本退休、安装事件、iOS指引及跨窗口更新保护。实际浏览器需验证Manifest安装条件、独立窗口、断网重新打开与重连、游戏输入/保存/新Run恢复、失败草稿保留与重试,并对桌面、390px手机和物理4K/150%缩放截图复核。生产构建另验收静态缓存和新版本等待/确认行为。