PWA 必须通过 manifest.json 的 protocol_handlers 数组注册 web+ 自定义协议，仅在已安装、HTTPS/localhost 环境、用户首次点击链接并授权后生效；protocol 必须以 web+ 开头，url 为相对路径且返回 200 并受 service worker 控制，参数通过 document.referrer 解析。

不能靠 HTML 标签或 JavaScript 调用注册 protocol_handlers——这是 manifest.json 的专属能力，且只在已安装、HTTPS/localhost 环境下由用户授权后生效。

manifest.json 里 protocol_handlers 怎么写才有效

必须是数组，每个对象含 protocol 和 url 两个字段，缺一不可。协议名推荐以 web+ 开头（如 "web+myapp"），Chrome 119+ 已禁用纯自定义前缀（如 myapp://）；url 必须是相对路径（如 "launch.html"），且该页面需返回 HTTP 200、被 Service Worker 控制、在 scope 或 start_url 覆盖范围内。

• protocol 值不区分大小写，但建议全小写
• url 不能带查询参数，也不能是重定向地址（301/302 会失败）
• 若用 index.html 作 handler 页面，确保它在 start_url 指向的路径下
• manifest 文件本身必须通过 <link rel="manifest" href="/manifest.json"> 声明，且服务器响应头含 Content-Type: application/manifest+json

点击 web+xxx:// 链接没反应？先查这几点

常见失败不是代码写错，而是环境或流程卡在某一步：

anything-to-html

将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。

下载

• 用户从未点击过该协议链接——首次触发才会弹出“是否允许 XXX 处理 web+myapp:// 链接？”提示，拒绝后需手动进 chrome://settings/handlers 清除或重置
• PWA 未真正安装：必须从地址栏点「添加到主屏幕」完成，仅访问网页不算；HTTP 环境（非 localhost）下完全无法注册
• url 对应页面未被 Service Worker 控制：打开 DevTools → Application → Service Workers，确认该页面 URL 在 “Controlled pages” 列表中
• 点击后新开标签页而非唤起 PWA：说明浏览器没识别为已注册 handler，大概率是 manifest 解析失败或协议未获授权

在 launch 页面里怎么拿到传入的协议 URL

浏览器不会把协议参数塞进 query string 或 window.location，而是通过 document.referrer 传递完整原始链接。你得自己解析它：

立即学习“前端免费学习笔记（深入）”；

if (document.referrer.startsWith('web+myapp://')) {
  const url = new URL(document.referrer);
  const id = url.searchParams.get('id');
  // 处理逻辑...
}

• document.referrer 只在 protocol_handlers 指定的页面中可靠存在，其他页面为空字符串
• 不要依赖 window.location.href，它通常是 about:blank 或空值
• 若需兼容多协议（如同时注册 web+myapp 和 mailto），需按 document.referrer 前缀分支判断
• 开发时可用 chrome://settings/handlers 查看当前已注册的协议条目，确认是否生效

最易忽略的一点：即使 manifest 写对了、Service Worker 也控制了页面，只要用户没点过一次对应链接，协议 handler 就永远处于“待授权”状态——没有后台静默注册这回事。