教程 ↗

PWA 页面能打开之后:核对动态响应、退出范围与统计队列

用可下载的本地 PWA 样例核对首响应 HTML、Worker 的 CSP、两个独立会话退出范围,以及真实 PostHog SDK 关闭后的队列事件。

PWA 在浏览器里能正常打开,三个问题仍可能藏在界面后面:首个 HTML 响应只有一个加载壳;静态页配置了 CSP,动态页却漏了;用户按下“退出”或关闭统计,服务端处理的范围与按钮文案不同。

我做了一个只在本机运行的 PWA 样例,把这些边界拆开观察。结果是:Worker 返回完整正文时,需要自己附带响应头;退出必须明确当前会话还是全部会话;统计开关还要处理关闭之前排队的事件。下载包保留故障路由、修复路由、实际响应与探针,方便按同一条件复查。

本地英文 PWA 实验界面,展示三个路由的响应比较与两个独立会话的退出结果

英文实验界面:左侧比较首响应,右侧显示自有 demo-auth 的双会话结果。

先把环境和观察对象固定

这次排错的线索来自一位 Reddit 开发者的 PWA 复盘。作者提到 hash 路由、Worker 页面响应头、Supabase 全局退出和 PostHog cookieless 模式。我没有复刻他的游戏;样例使用自有开发任务文字,关注这几个交接点。

环境锁定为 Wrangler 4.147.0、PostHog JS 1.435.9;核对 Supabase 参数的包为 @supabase/supabase-js 2.117.2 及它安装的 Auth SDK。Cloudflare Worker 使用兼容日期 2026-10-05,所有请求在本机回环地址间完成。样例包含 manifest 与已在 Chromium 页面中控制该页的 service worker。service worker 采用纯网络路径,不缓存 HTML、登录响应或统计请求。

实际运行的部分是 Cloudflare 本地 Worker、两个 HTTP 客户端会话和真实 PostHog 浏览器 SDK。认证服务 demo-auth 是我写的本地教学服务;统计接收器只解析 SDK 的 JSON batch。Supabase 云端撤销、PostHog 服务端 cookieless 哈希、后台入库与项目配置没有参与本次实测。PWA 的操作系统安装、离线能力和原帖设备表现也在观察范围之外。

下载可复现样例与响应快照。需要 Node.js 22.12 或更高版本;依赖由 npm 锁文件固定。解压后先运行 npm ci,它会通过 prepare 步骤复制真实 PostHog SDK,再分别开三个终端:

# 终端 1:本地会话服务和事件接收器
npm run collector

# 终端 2:Cloudflare 本地 Worker,端口 8791
npm run dev

# 终端 3:响应与双会话断言
npm run probe

打开 http://127.0.0.1:8791/lab,依次点击 Compare responses 和 Run analytics cases。如果 Wrangler 提示静态素材监听不可用,在 probe 生成会话结果后重启 dev,让页面加载最新结果。下载包的 observed/ 是这次实测快照;重新运行探针才能观察你的环境。

浏览器显示的正文,何时进入 HTTP 响应

样例给同一段任务文字准备了两种路径。/shell#task 的原始 HTML 只有“Loading task…”和一个空容器,shell.js 执行后才把任务文字插进去。/fixed/task 则由 Worker 在构造 HTML 时写入任务正文。

在页面里看到文字,说明渲染后的 DOM 有内容。要判断首响应是否包含内容,可以直接保存 GET 响应体:

curl -sS -D shell.headers http://127.0.0.1:8791/shell -o shell.html
curl -sS -D fixed.headers http://127.0.0.1:8791/fixed/task -o fixed.html

#task 是浏览器端 fragment,不随 HTTP 请求发给服务端。把 task 放进 hash 之后,Worker 收到的仍是 /shell;要按任务直接生成页面,需要能在服务端区分的路径或查询参数。

这次探针对三个原始响应检查同一句任务文字与 CSP:

路由HTTP 状态首响应含任务正文CSP 响应头
/shell#task200无有,来自静态 _headers
/broken/task200有无
/fixed/task200有有,由 Worker 设置

静态页也可以在构建时写好完整正文;这里的空壳只是故障样本。选静态生成还是按请求渲染,应取决于内容更新与访问控制的需要。原帖“Google 只看到约 20 个词”是作者自述,我没有他的搜索后台数据。这里验证到的是原始响应和浏览器渲染的差异,Google 执行 JavaScript 后如何处理页面需另行观察。原帖提到的 IndexNow 通知也只是一条通知步骤;本文没有发出通知或核验索引结果。

动态正文生成了,CSP 为什么仍然缺失

public/_headers 对 /* 设置 CSP,所以静态壳页面带有策略。故障 Worker 路由 /broken/task 虽然匹配同一个 URL 模式,但它直接返回 new Response(html),没有经过静态资源响应的加头步骤。

Cloudflare Static Assets 响应头文档明确区分了这两条路径:_headers 作用于静态资源响应,Worker 代码生成的响应需要在 Worker 中附加。于是修复放在生成响应的地方:

const headers = new Headers({
  'Content-Type': 'text/html; charset=utf-8',
  'Content-Security-Policy': csp,
  'Cache-Control': 'no-store',
  'X-Content-Type-Options': 'nosniff',
})
return new Response(html, { headers })

本次样例的 CSP 只允许同源脚本、样式、连接、图片和 service worker,另限制 frame-ancestors、base-uri 和 object-src。实验 SDK 文件在同源加载,采集也只走同源本地代理。这份策略适合样例;接入第三方脚本、跨域认证或图片时,需要按真实资源重新设计和检查。

probe.mjs 除了断言故障响应缺 CSP、修复响应有 CSP,还比较静态页与修复页的完整 CSP 字符串相等。只检查“有这个头”会漏掉两份策略逐渐漂移的问题。样例中两份值仍分别存储,所以断言是必要的约束;正式工程可以从一个策略源生成静态文件和 Worker 常量。

继续检查你的错误响应、重定向和登录后的路径:每个直接生成响应的分支都可能有独立的头部行为。私人页面的缓存也要和正文一起判断。本例为修复页使用 no-store,没有复用公共 HTML 缓存。修改代理响应头时可以保留 response.body 流,避免为了加头先把大响应完整读入内存。

退出当前会话,需要用第二个会话观察

在一个标签页里删除登录信息,只能说明这个客户端的状态变了。要检查“退出这台设备”是否扩大到其他登录,需要第二个独立会话。样例 probe 用两份互不共享的 HTTP cookie jar,为同一个自有样例账号建立 A、B 两个服务端会话。

先让 A 发起 scope: "local" 退出,随后分别请求 /demo-auth/me:A 得到 authenticated: false,B 得到 true。再登录 A,让 A 使用样例的默认 global 退出,两个客户端的认证检查都得到 false,服务端剩余会话清单为空。

demo-auth 操作A 会话检查B 会话检查服务端剩余会话
A 使用 local 退出falsetrueB
A 使用默认 global 退出falsefalse空

这个测试验证了本地服务的退出作用域,以及“服务端状态—第二客户端请求—界面状态”这条检查方法。demo-auth 采用服务端查表会话,撤销后下一次请求立即失败;它的机制与 Supabase 的 JWT 机制不同。

Supabase 的 JavaScript signOut 文档和本次安装的 GoTrueClient.ts 都把默认 scope 写为 global。使用 Supabase 的产品如果按钮要表达当前会话退出,应显式传参:

const { error } = await supabase.auth.signOut({ scope: 'local' })
if (error) {
  // 在产品里显示或处理实际错误,再决定界面状态
}

同一文档说明,退出撤销的是相应 refresh token;已发出的 access-token JWT 通常要到过期才失效。因此,测试 Supabase 时要分别记录本地 storage、refresh 是否失败、受保护 API 是否仍接受未过期 JWT,以及另一客户端怎样更新界面。仅看到第二个页面还显示“已登录”或立即收到一次成功响应,都不足以定位撤销失败。这次核对止于官方说明和 SDK 参数,Supabase 云端跨会话结果仍待真实服务环境验证。

统计关闭要检查两种队列

PostHog 的 cookieless_mode: "always" 会持续使用 cookieless 捕获。在 1.435.9 的源码中,opt_out_capturing() 遇到这个配置会警告并返回;is_capturing() 仍返回 true。on_reject 则在拒绝后转入 cookieless 路径,也不等同于停止发事件。具体含义见 PostHog 配置文档。

我把真实 SDK 的 api_host 指向本机接收器,关闭自动捕获、pageview、replay、flags、压缩和外部脚本加载,以便只观察手动事件。首次解析时,我把 SDK 请求当作裸数组,结果丢了事件字段;核对实际版本的 request.js 后,接收器改为读取 { batch: [...] },才得到正确事件名。这也说明只统计“收到三个请求”会漏掉测量代码本身的问题。

最终结果中,接收器收到三个事件:

测试接收器实际收到说明
always 模式调用 opt-out 后 capturealways_after_optoutSDK 仍在捕获
普通模式,capture 入队后立即 opt-outnormal_queued_before_off关闭前已进入 SDK 队列的事件仍发送
普通模式,opt-out 后再 capture无 normal_after_off新捕获被阻止
修复模式关闭时丢弃应用队列,再尝试捕获无关闭前待发或关闭后事件尚未交给 SDK 的事件被清空
修复模式重新打开统计后捕获fixed_after_on恢复发送路径正常

真实 PostHog JS SDK 实验结果,普通模式的旧队列事件仍发送,修复模式关闭时清空应用队列

本地接收器的事件名与 SDK 队列观测。

这里有两种等待区:应用在 SDK 加载前存下的事件,以及 SDK 自己为批量发送保留的事件。before_send 会在事件进入发送处理路径时过滤;已经经过它并进入 SDK 队列的旧事件,不能假设在用户改开关后自动再过滤一次。

样例的修复把等待区留在应用里,同时关闭该 SDK 实例的批量发送。开关在入应用队列、交给 SDK、before_send 三处核对:

let enabled = true
let pending = []

posthog.init('YOUR_PROJECT_TOKEN', {
  request_batching: false,
  before_send: event => enabled ? event : null,
  // 其余配置按项目设置;样例还关闭了自动捕获等路径
})

function track(event, properties) {
  if (enabled) pending.push({ event, properties })
}
function turnOff() {
  enabled = false
  pending = []
}
function dispatch() {
  if (!enabled) return
  for (const item of pending) {
    posthog.capture(item.event, item.properties, { send_instantly: true })
  }
  pending = []
}

实际样例还故意在 Off 后直接调用一次 SDK,确认 before_send 阻止绕过包装层的新事件。它读取私有 _requestQueue 字段只用于诊断,没有修改 SDK 内部队列;生产实现依赖的应是公开 API。

这份修复的约定是:清空还在应用等待的事件,并阻止之后的新捕获。已经发到网络中的请求、SDK 重试、别的采集实例和以前保存的数据需要各自的处理策略。产品若承诺“关闭后停止所有传输”,验收还要覆盖这些路径。官方 JS 使用文档也说明浏览器 SDK 没有供自定义事件使用的公开 flush() 方法;不要凭别的 SDK 经验臆造关闭或清空 API。

把按钮的承诺写成可观察的边界

这次样例里,首响应正文与 CSP 是两个独立断言;退出范围靠第二个客户端再次请求核对;统计开关同时观察新事件、应用等待队列和 SDK 旧队列。这样排错时,读者可以说清究竟修复了哪一步。

把同一方法带回自己的 PWA:保存有代表性的首响应与头部,用两份独立会话检查退出范围,在统计关闭前后给事件明确命名,再去接收端核对。保留修复前的失败样本和依赖版本,后续升级时才有具体的回归目标。

← 返回列表