跳到主要内容

P0-3 H5 兼容性与断网降级实测

2026-11-16。对应 调研缺口清单.md 第 7 步。 目标:把「H5 载体到底会不会在手机上坏掉」从猜测变成可复跑的数字,并给出免 ICP 备案的前提(C1)的技术证据。 结论先行:15 个视口全通过、断网可启动可推进、存档不丢;但有 5 项模拟器测不了,必须真机。


〇、判定​

项判定证据强度
多机型布局(竖屏 13 个视口)✅ 通过几何 + 命中测试,可复跑
横屏✅ 已按设计阻截(不重排)实测横屏正文区只剩 79px / 2 行
文字被浮层遮挡✅ 未出现elementFromPoint 网格命中,可见比 1.00
断网启动(C1 核心玩法离线可完成)✅ 成立严格模式 transferSize=0,见第四节
刷新 / 切后台丢档✅ 不丢idx 0→1→1,bootSource=restore
真机 Safari / TapTap 容器 WebView⬜ 未验证模拟器替代不了,见第九节 6 条

一句话:技术形态没有问题,风险已经从「会不会坏」收窄成「在别人家的 WebView 里会不会不一样」。


一、为什么不是「真机」​

本机没有可用的 iOS / Android 测试机,也没有 TapTap 客户端容器。因此用无头 Chrome + CDP Emulation.setDeviceMetricsOverride 模拟视口与 DPR,跑一份真实可交互的页面(不是静态稿), 把能自动化的部分钉死。

这套方法能证明什么

  • 几何布局:在给定 CSS 尺寸下,正文区能吃下几行、选项能不能放完、有没有横向溢出
  • 遮挡:浮层与正文/按钮是否存在像素级重叠(用命中测试,不看 z-index 猜)
  • 热区尺寸、字号、对比度、200% 字体缩放
  • Service Worker 离线启动、localStorage 存档恢复、后台冻结后回前台

这套方法不能证明什么

  • iOS Safari 地址栏收放时 100vh 的真实行为(WebKit 特有,且与是否滚动绑定)
  • env(safe-area-inset-*) 的真实取值(模拟器里恒为 0px)
  • 字体度量差异导致的中文换行差异(iOS 用 PingFang,行高与断行点未必一致)
  • TapTap 小游戏容器内 WebView 的内核版本与嵌套滚动行为
  • 惯性滚动、长按选中、双指缩放等触摸手感
  • 低端机的渲染性能(首屏耗时、长列表掉帧)

所以下文所有「✅」都只对最后一列负责:布局与离线逻辑成立,不等于「兼容性通过」。真正的验收仍然是第九节那张表。


二、测试台(可复跑)​

h5-rig/
├── index.html # 三段式:HUD / 正文滚动区 / 选项区 + 固定广告底栏 + 横屏遮罩
├── style.css # 含 100vh→100dvh 兜底、安全区 padding、48px 热区
├── app.js # 最小闭环:事件→选择→推进;每次选择静默落盘;注册 SW
├── sw.js # 离线壳,预缓存 5 个文件
├── selftest.js # 页内自检器:12 项判定,全部基于几何与命中测试(竖屏执行 11 项)
├── h5_probe.mjs # CDP 驱动:15 机型 × 自检 + 阴性对照 + 断网 + 存档 + 切后台
└── out/ # compat.json + 17 张截图(15 机型 + 阴性对照 + 断网态)+ contact-sheet.png

复跑:

cd h5-rig && (python3 -m http.server 4399 --bind 127.0.0.1 &) ; sleep 1
node h5_probe.mjs http://127.0.0.1:4399/ ./out
pkill -f "http.server 4399"

服务必须与探针写在同一条命令里(跨命令起的后台进程会被回收,Chrome 会截到 refused to connect 错误页)。


三、设备矩阵结果​

机型CSS 尺寸DPR正文区容量长文滚动正文可见比对比度选项热区判定
320-se1320×568210 行0.5 屏1.0015.55:148px✅
320-se1-stress320×568210 行1.4 屏1.0015.55:148px✅
280-fold-closed280×6532.62513 行0.5 屏1.0015.55:148px✅
280-fold-closed-stress280×6532.62512 行1.3 屏1.0015.55:148px✅
360-redmi9a360×640212 行0.3 屏1.0015.55:148px✅
360-android-mid360×800318 行0.2 屏1.0015.55:148px✅
375-iphone8375×667213 行0.3 屏1.0015.55:148px✅
375-13mini375×812318 行0.2 屏1.0015.55:148px✅
390-iphone14390×844320 行0.2 屏1.0015.55:148px✅
393-15pro393×852320 行0.2 屏1.0015.55:148px✅
412-android-big412×9152.62522 行0.2 屏1.0015.55:148px✅
430-15promax430×932323 行0.2 屏1.0015.55:148px✅
744-ipadmini744×1133230 行0.1 屏1.0015.55:148px✅
landscape-844x390844×3903—————横屏阻截生效
landscape-800x360800×3603—————横屏阻截生效

六联对比图:h5-rig/out/contact-sheet.png(280 外屏 / 320 常规 / 320 长文 / 390 主流 / 横屏阻截 / 阴反对照)

三行读法:

  1. 小屏不是瓶颈,横屏才是。 320 宽仍有 10 行容量(约 180 字),而横屏 800×360 只剩 79px = 2 行—— HUD 41px + 三个选项 168px + 广告底栏 56px 把 360 的高度吃光了。这不是「再挤一挤」能解决的,见第七节。
  2. 237 字的长事件在 320 宽要滚 1.4 屏。 滚动本身正常,但截图里正文被裁在「怀里那半块干粮硬得」这样 半句中间,页面上没有任何「还有下文」的提示 —— 这正是竞品评论「下面文字全挡住了」的一种真实形态。
  3. 三个无争议项:热区恒 48px、正文对比度 15.55:1(远超 AA 4.5)、系统 200% 字体缩放下横向溢出 0px。

四、断网降级(资质 C1 的技术落点)​

C1 是 H5上架资质核验.md 里免 ICP 备案的前提:核心玩法要能离线完成。这次把它做出来了:

证据值含义
navigator.onLinefalse确已离线
navigator.serviceWorker.controllertrue页面由 SW 接管
caches.keys()["xx-shell-v1"]预缓存已建立
离线启动booted=true断网刷新能进游戏
离线推进advancedOffline=true点击选项能换事件,不是只出个壳
严格模式启动strictBooted=truePage.reload({ignoreCache:true}) 绕过 HTTP 磁盘缓存后仍能启动
严格模式 transferSize0整页 0 字节网络传输 = 完全由 SW 缓存供给
离线内布局自检pass=true离线状态下布局判定同样通过

为什么非要多做「严格模式」这一遍:第一次跑的普通刷新里 transferSize=2049, 说明那一遍可能是 Chrome 的 HTTP 磁盘缓存兜住的,不是 SW。清缓存或换设备就会白屏, 而白屏在玩家侧就是「打开就闪退」。加上 ignoreCache 之后 transferSize 归零,才是可控的离线能力。

残余风险(写进运维,不是写进代码)

  • 首访 0 秒断网:SW 还没 install 完就断网 → 无缓存可用。缓解:启动后 3 秒内完成 install(当前壳共 5 个文件、约 12KB,实测毫秒级)。
  • 用户清站点数据 / 隐私模式:SW 缓存与 localStorage 一并清空 → 回到「首次访问」,进度丢失。这是所有 H5 的共同上限,不做承诺。
  • 跨设备同步:本方案不做。云存档属于官方定义的「附加服务」,一旦依赖它就不再是「不联网」,会牵出 ICP —— 与裁决二直接冲突,明确放弃。

五、存档与切后台​

场景结果
点击选项后落盘idx 0 → 1,ling 0 → 5,picks 0 → 1
刷新页面idx 仍为 1,bootSource=restore,标题回到「溪边石上」而非首条事件
切后台(Page.setWebLifecycleState('frozen') → active)回前台存活,存档 idx=1 未变
离线 + 严格强刷idx=1 保留,标题一致

第一版这里有个坑值得记下来:?reset=1 参数留在地址栏里,刷新时又把存档清了一次, 表现为「刷新后回到第一条事件」。真实玩家场景里没有 reset 参数,所以这是测试台的 bug 不是产品的 bug, 但它的症状与「回档」完全一样 —— 说明这类问题必须靠自动化断言抓,肉眼看截图看不出来。

竞品侧对照:H5 组「存档丢失/回档」提及率是 APK 组的 4.10 倍(1.2% vs 0.3%)。 我们的做法是每次 pick 同步落盘(不做 30 秒/5 分钟节流),代价是每局多写十几次 localStorage,收益是彻底消掉这一类差评。


六、阴性对照:证明「全过」不是检测器写松了​

只有「全部通过」的报告是不可信的。所以专门做一个故意坏掉的版本(?fragile=1, 去掉给固定底栏留的 padding),看检测器能不能抓到:

版本判定抓到的问题
正常(320×568)✅ 通过—
对照(?fragile=1)❌ 按预期失败opt-not-occluded(第 3 个选项命中比 0.00)、no-overlap-adbar(底栏压住 46px)

对照截图里第三个选项整条消失、只剩前两条 —— 与竞品「按键完全挡住😅」是同一个画面。

顺带修正了检测器自己的两个误判(第一版 15 机型里 5 个 FAIL 全是假的):

误判原因修法
长文本判「被遮挡」采样点算到了滚动容器外面,把「超出容器」当成「被浮层盖住」采样点先与容器可见矩形求交
iPad 判「首屏不足 3 行」量的是这一次内容有几个字(iPad 上 75 字只占 2 行)改量容器容量 stageH / lineHeight,与内容长短脱钩

这条经验直接适用于以后所有 UI 验收:判据必须量「结构」,不能量「这一次恰好长什么样」。


七、三个真问题​

1. 横屏(已按设计阻截)​

800×360 下正文区 79px、844×390 下 109px。重排需要把选项改成左右两栏 + 隐藏 HUD, 改完之后正文区也就 150px 上下,而且横屏玩家本来就是极少数。 所以不做适配,做阻截:@media (orientation: landscape) and (max-height: 520px) 显示全屏遮罩 「请竖屏游玩」。遮罩自身也进了自检(rotate-gate-covers:矩形盖满视口 + 中心点命中自己), 避免出现「遮罩只盖一半、底下按钮还能点」这种二次事故。

若 TapTap 容器强制横屏,这条要推翻重做。提交前必须先在容器里确认方向策略。

2. 长文没有「还有下文」的提示​

320×568 截图中正文正好裁在「……那半块干粮硬得」处,句中断开且没有任何视觉提示。 玩家会以为文字就到这里断了 —— 与「文字被挡住」的体感一致,但原因完全不同, 所以这是必须单独修的一项:正文溢出时在滚动区底部加一层约 24px 的渐隐遮罩(pointer-events:none), 滚到底时淡出。禁止的做法:用遮罩盖住正文当装饰(那是真遮挡)。

3. iOS 15.4 以下没有 dvh​

已改成 height:100vh; height:100dvh; 双写。但 vh 在 iOS Safari 里包含地址栏高度, 落地表现是底部约 60~80px 被裁 —— 正好裁在选项区。这一条模拟器测不出来, 只能真机验,列为第九节第 1 项。


八、写进 SPEC 的硬约束(R1~R8)​

#约束出处
R1视口高度必须 100vh + 100dvh 双写,禁用裸 100vh第七节 3
R2底栏高度用 CSS 变量 --adbar-h,#app 的 padding-bottom = calc(var(--adbar-h) + env(safe-area-inset-bottom));任何固定浮层都必须在这个等式里阴性对照压住 46px
R3正文滚动区溢出时,底部必须给「还有下文」渐隐提示(pointer-events:none,滚到底淡出)第七节 2
R4选项热区 min-height: 48px、宽度撑满、touch-action: manipulation(禁双击缩放延迟)全机型 48px
R5正文 16px / 1.75,对比度 ≥ 4.5:1;系统 200% 字体缩放不得横向溢出15.55:1 / 溢出 0px
R6横屏(max-height:520px)一律阻截,不重排;遮罩必须盖满且中心点命中自己79px 实测
R7SW 预缓存清单必须覆盖启动全部依赖(html/css/js/selftest),首启 3 秒内完成 install严格模式 transferSize=0
R8每次选择同步落盘,不做节流;visibilitychange:hidden 与 pagehide 各补存一次竞品回档 4.10x

R2 和 R6 是这次新增的,且都是「改一行 CSS 就能避免一整类差评」的类型。


九、仍需真机验证(6 条,模拟器替代不了)​

按风险排序,每条给了具体做法与判据:

#待验做法通过判据
1iOS Safari 地址栏收放iPhone 真机 Safari 打开,下滚触发地址栏收起,再回滚收起/展开时正文与选项均不被裁,无跳动
2安全区(刘海/Home 条)iPhone 14 Pro + 一台老 iPhone(无刘海)各测底栏按钮不被 Home 条压住;顶部 HUD 不被灵动岛切
3TapTap 容器内 WebView上传测试版小游戏,在 TapTap 客户端内打开与 Safari 表现一致;横屏策略与容器一致(第七节 1 的推翻条件)
4软键盘(暂时无输入框,首版无风险)若加入「自创流派命名」则需要键盘弹出时选项不被顶出可视区
5低端安卓渲染Redmi 9A 级真机,连点 30 次选项无掉帧卡顿、无白屏、无滚动粘滞
6弱网(非断网)限速 3G,首访后立刻杀进程再进SW install 完成前不出现白屏;进度不丢

其中 1、2、3 是上线前必须过的三条,其余三条可在内测期补。


十、与前面结论的衔接​

  • 与 C1 的关系:H5上架资质核验.md 说「断网能玩核心玩法即不算联网」→ 本文第四节给了技术闭环, 但**「技术上能离线」不等于「资质上算离线」**,C3(提交前后台「计算所需资质」截图留证)仍然是最后一道闸。
  • 与 4.10x 回档率的关系:存档问题在竞品里是 H5 组最突出的技术差评源,R8 是针对它的直接对策。
  • 与 P1-1 的关系:文案四道闸里「盲读测试」需要真机内测,本文第九节第 3 项跑通即可并入。
  • 已裁决(2026-11-16):首版事件 300 条(「150 条精修」建议作废)。它决定长文本的出现频率, 也就是第七节第 2 条那个「没有下文提示」问题的高发场景 → R3 不是可选优化项,是 300 条库的前提。